Returns the performance review cycles visible to the caller. Required scope: r_reviews.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
This endpoint uses ther_reviewsscope, which must be enabled through the Integrations section found within the Settings menu.
Requires a user token, or an account token together with the member_id query parameter (the request is then evaluated with that member's permissions). An account token without member_id gets 403 Account tokens need a member_id for this operation. member_id is ignored for user tokens.
The member must be able to view review cycles: either through the View review cycles permission (global or scoped role), or through View employee directory in an account with performance reviews enabled.
Archived and deleted cycles are never returned. Members without the global View review cycles permission only see cycles they participate in (as reviewee, manager, reviewer or within their reporting line) or that fall within their scoped role, and never see cycles in the draft state.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| states | array | Filter by cycle state, e.g. states[]=active&states[]=ended. Allowed values: draft, scheduled, in_preparation, active, ended. Defaults to all of them |
| limit | integer | Maximum number of cycles to return (minimum 1) |
| offset | integer | Number of cycles to skip (minimum 0) |
Pagination
limit and offset are optional. When both are omitted, every matching cycle is returned in a single response. Cycles are ordered by id; total_count always reflects the full number of matches.
Results
{
"total_count": 1,
"review_cycles": [
{
"id": "4d3",
"name": "Annual Review 2024",
"description": "Company-wide annual performance review",
"state": "active",
"start_date": "2024-11-01T00:00:00.000Z",
"end_date": "2024-11-30T00:00:00.000Z",
"review_period_start": "2024-01-01T00:00:00.000Z",
"review_period_end": "2024-11-01T00:00:00.000Z",
"timezone": null,
"employee_count": 4,
"draft_count": 2,
"completed_count": 1,
"not_started_count": 1,
"share_start_date": null,
"share_deadline": null,
"sign_deadline": null,
"employee_meeting_deadline": null,
"customization_start_date": "2024-10-01T00:00:00.000Z",
"customization_end_date": "2024-10-15T00:00:00.000Z",
"has_manager_review": true,
"has_self_review": true,
"has_peer_reviews": false,
"has_upwards_reviews": false
}
]
}| key | type | description |
|---|---|---|
| total_count | integer | Number of review cycles matching the filters |
| review_cycles | array | Array of review cycle objects (see GET /review-cycles/:id for the cycle payload) |
Error responses
Error bodies come in three shapes. 400 validation errors are a JSON object keyed by the invalid parameter, e.g. {"limit": {"code": "number.max", "message": "\"limit\" must be less than or equal to 200"}}. 401 and 403 are plain-text bodies, e.g. Required scopes missing: ["r_reviews"], or Forbidden when the member lacks permission. 404 is JSON, e.g. {"message": "Review cycle not found"}.
| Status | Condition |
|---|---|
| 400 | Invalid query parameter (for example an unsupported value in states, such as archived) |
| 401 | Missing or invalid token |
| 403 | Missing r_reviews scope, account token without member_id, or the member cannot view review cycles |