Skip to content

Project iterations API

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

This page describes the project iterations API. There's a separate group iterations API page.

We no longer have project-level iterations, but you can use this endpoint to fetch the iterations of the project's ancestor groups.

List project iterations

Returns a list of project iterations.

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]. Introduced in GitLab 16.2.
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. Introduced in GitLab 16.7.
updated_before datetime no Return only iterations updated before the given datetime. Expected in ISO 8601 format (2019-03-15T08:00:00Z). Introduced in GitLab 15.10.
updated_after datetime no Return only iterations updated after the given datetime. Expected in ISO 8601 format (2019-03-15T08:00:00Z). Introduced in GitLab 15.10.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "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"
  }
]