For AI agents: markdown of this page — /docs-content-en/scrum/sprints/list.md documentation index — /llms.txt

List sprints

GET /v1/scrum/sprints

Returns the sprints of the Bitrix24 account's scrum projects. The id field supplies the sprint identifier used by board stage operations and the single-sprint read.

Parameters

Parameter Type Default Description
groupId (query) number — Scrum project ID. List: GET /v1/workgroups. Without the parameter, the response contains every sprint the key can see
limit (query) number 200 How many sprints to return, from 1 to 1000

Pagination. Pages are fetched automatically — the response arrives as a single array of up to limit records, and the method has no offset parameter. A limit above 1000 is clamped to 1000 without an error.

Examples

curl — personal key

Terminal 
curl https://vibecode.bitrix24.com/v1/scrum/sprints \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/scrum/sprints \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/sprints', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
const active = data.filter((sprint) => sprint.status === 'active')
console.log(active.map((sprint) => `${sprint.id}: ${sprint.name}`))

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/sprints', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log(data.map((sprint) => sprint.name))

Response fields

Field Type Description
success boolean Always true on success
data array Array of sprints
data[].id number Sprint ID. The same value as sprintId in stage operations
data[].groupId number Scrum project ID. List: GET /v1/workgroups
data[].entityType string Record type. For a sprint — sprint
data[].name string Sprint name
data[].goal string Sprint goal. An empty string is returned when no goal is set
data[].sort number Sprint order within the project
data[].createdBy number ID of the sprint author. List: GET /v1/users
data[].modifiedBy number ID of the employee who last changed the sprint. List: GET /v1/users
data[].dateStart string Sprint start in ISO 8601 with the account's UTC offset
data[].dateEnd string Sprint end in ISO 8601 with the account's UTC offset
data[].status string planned, active or completed

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 9,
      "groupId": 45,
      "entityType": "sprint",
      "name": "Sprint 2",
      "goal": "",
      "sort": 0,
      "createdBy": 29,
      "modifiedBy": 29,
      "dateStart": "2023-09-01T01:00:00+00:00",
      "dateEnd": "2024-04-16T12:20:42+00:00",
      "status": "completed"
    },
    {
      "id": 11,
      "groupId": 45,
      "entityType": "sprint",
      "name": "Sprint 3",
      "goal": "",
      "sort": 0,
      "createdBy": 29,
      "modifiedBy": 29,
      "dateStart": "2023-09-15T01:00:00+00:00",
      "dateEnd": "2023-09-29T01:00:00+00:00",
      "status": "active"
    },
    {
      "id": 21,
      "groupId": 53,
      "entityType": "sprint",
      "name": "Sprint 6",
      "goal": "",
      "sort": 0,
      "createdBy": 1,
      "modifiedBy": 1,
      "dateStart": "2024-06-05T01:00:00+00:00",
      "dateEnd": "2024-06-19T01:00:00+00:00",
      "status": "active"
    }
  ]
}

Error response example

400 — an invalid groupId value:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupId must be a positive integer"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS groupId is not a positive integer
400 INVALID_PARAMS limit is not a positive integer
422 BITRIX_ERROR Bitrix24 returned an error, e.g. "Access denied" when the key's user has no access to the scrum project
403 SCOPE_DENIED The key lacks the task scope
401 TOKEN_MISSING The key has no tokens configured

The full list of common API errors — Errors.

Known specifics

  • Without groupId the sprints of different projects are interleaved. The response is not grouped by project, so split the result on your side by each record's groupId field.
  • Completed sprints stay in the result. The response is not limited to the project's current sprint. If you only need the current one, use GET /v1/scrum/sprints/active.

See also