Sample - GitHub REST API
GET/agents/tasks

List tasks

[!NOTE] This endpoint is in public preview and is subject to change.

Returns a list of tasks for the authenticated user

Fine-grained access tokens for "List tasks"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Agent tasks" repository permissions (read)

GitHub App installation access tokens are not supported for this endpoint.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

7 parameters
per_pageintegeroptional
The number of results per page (max 100).
Default:30
pageintegeroptional
The page number of the results to fetch.
Default:1
sortstringoptional
The field to sort results by. Can be `updated_at` or `created_at`.
Allowed:updated_atcreated_atDefault:updated_at
directionstringoptional
The direction to sort results. Can be `asc` or `desc`.
Allowed:ascdescDefault:desc
statestringoptional
Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`.
is_archivedbooleanoptional
Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`.
Default:false
sincestringoptional
Only show tasks updated at or after this time (ISO 8601 timestamp)

5 status codes
200Tasks retrieved successfully
tasksarray<object>required
List of tasks
total_active_countintegeroptional
Total count of active (non-archived) tasks
total_archived_countintegeroptional
Total count of archived tasks
400Bad request
messagestringrequired
Summary message (e.g. "Validation Failed", "Not Found")
errorsarray<object>optional
List of validation errors (present only for 422 responses)
documentation_urlstringrequired
URL to relevant API documentation
401Authentication required
messagestringrequired
Summary message (e.g. "Validation Failed", "Not Found")
errorsarray<object>optional
List of validation errors (present only for 422 responses)
documentation_urlstringrequired
URL to relevant API documentation
403Insufficient permissions
messagestringrequired
Summary message (e.g. "Validation Failed", "Not Found")
errorsarray<object>optional
List of validation errors (present only for 422 responses)
documentation_urlstringrequired
URL to relevant API documentation
422Validation Failed
messagestringrequired
Summary message (e.g. "Validation Failed", "Not Found")
errorsarray<object>optional
List of validation errors (present only for 422 responses)
documentation_urlstringrequired
URL to relevant API documentation

Error handling

A 400 is returned: Bad request. A 401 is returned: Authentication required. A 403 is returned: Insufficient permissions. A 422 is returned: Validation Failed.