Help us learn about your current experience with the documentation. Take the survey.

Project iterations API

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use this API to access project iterations.

For group iterations, use the group iterations API.

Projects do not have their own iterations. Use this endpoint to list the iterations of a project’s ancestor groups.

List all project iterations

Lists all iterations for a specified project.

Iterations created by Enable automatic scheduling in Iteration cadences return null for the title and description fields.

GET /projects/:id/iterations
GET /projects/:id/iterations?state=opened
GET /projects/:id/iterations?state=closed
GET /projects/:id/iterations?search=version
GET /projects/:id/iterations?include_ancestors=false
GET /projects/:id/iterations?include_descendants=true
GET /projects/:id/iterations?updated_before=2013-10-02T09%3A24%3A18Z
GET /projects/:id/iterations?updated_after=2013-10-02T09%3A24%3A18Z

Attribute	Type	Required	Description
`state`	string	no	‘Return `opened`, `upcoming`, `current`, `closed`, or `all` iterations.’
`search`	string	no	Return only iterations with a title matching the provided string.
`in`	array of strings	no	Fields in which fuzzy search should be performed with the query given in the argument `search`. The available options are `title` and `cadence_title`. Default is `[title]`.
`include_ancestors`	boolean	no	Include iterations for parent group and its ancestors. Defaults to `true`.
`include_descendants`	boolean	no	Include iterations for parent group and its descendants. Defaults to `false`.
`updated_before`	datetime	no	Return only iterations updated before the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`).
`updated_after`	datetime	no	Return only iterations updated after the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`).

Example request:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/iterations"

Example response:

[
  {
    "id": 53,
    "iid": 13,
    "group_id": 5,
    "title": "Iteration II",
    "description": "Ipsum Lorem ipsum",
    "state": 2,
    "created_at": "2020-01-27T05:07:12.573Z",
    "updated_at": "2020-01-27T05:07:12.573Z",
    "due_date": "2020-02-01",
    "start_date": "2020-02-14",
    "web_url": "http://gitlab.example.com/groups/my-group/-/iterations/13"
  }
]