List all project iterations

GET

/api/v4/projects/{id}/iterations

• GitLab REST API

Lists all iterations for a specified project. Iterations created by Enable automatic scheduling in iteration cadences return null for the title and description fields. This feature was introduced in GitLab 13.5.

Authorizations

• http
• oauth2

Parameters

Path Parameters

id

required

One of:

string

string

integer

integer

The ID or URL-encoded path of the project

Example

5

Query Parameters

state

string

default: all nullable

Allowed values: opened upcoming started current closed all

Return “opened”, “upcoming”, “current (previously started)”, “closed”, or “all” iterations. Filtering by started state is deprecated starting with 14.1, please use current instead.

Example

opened

search

string

nullable

The search criteria for the title of the iteration

Example

version

in

Array<string>

nullable

Fields in which fuzzy search should be performed with the query given in the argument search. The available options are title and cadence_title. Defaults to [title]

Example

[
  "title",
  "cadence_title"
]

include_ancestors

boolean

default: true nullable

Include iterations from parent and its ancestors

Example

false

include_descendants

boolean

nullable

Include iterations from parent and its descendants

Example

true

updated_before

string format: date-time

nullable

Return milestones updated before the specified datetime. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ

Example

2023-02-28T21:22:12Z

updated_after

string format: date-time

nullable

Return milestones updated after the specified datetime. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ

Example

2023-02-28T21:22:12Z

page

integer

default: 1 nullable

Current page number

Example

1

per_page

integer

default: 20 nullable

Number of items per page

Example

20

Responses

200

OK

Media type application/json

object

id

integer format: int64

iid

integer

sequence

integer

group_id

integer format: int64

title

string

description

string

state

integer

created_at

string format: date-time

updated_at

string format: date-time

start_date

string format: date

due_date

string format: date

web_url

string

Example

{
  "id": 1,
  "iid": 1,
  "sequence": 1,
  "group_id": 1,
  "title": "Iteration I",
  "description": "Iteration description",
  "state": 1,
  "created_at": "2022-01-31T15:10:45.080Z",
  "updated_at": "2022-01-31T15:10:45.080Z",
  "start_date": "2022-01-01",
  "due_date": "2022-01-31",
  "web_url": "https://gitlab.example.com/groups/gitlab-org/-/iterations/1"
}

400

Bad Request

404

Not Found