Sample - GitHub REST API
GET/agents/tasks/{task_id}

Get a task by ID

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

Returns a task by ID with its associated sessions

Fine-grained access tokens for "Get a task by ID"

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.

1 parameter
task_idstringrequired
The unique identifier of the task.

6 status codes
200Task retrieved successfully
idstringrequired
Unique task identifier
urlstringoptional
API URL for this task
html_urlstringoptional
Web URL for this task
namestringoptional
Human-readable name derived from the task prompt
creatorobjectoptional
The entity who created this task
creator_typestringoptional
Type of the task creator
Allowed:userorganization
user_collaboratorsarray<object>deprecatedoptional
User objects of collaborators on this task
ownerobjectoptional
The owner of the repository
repositoryobjectoptional
The repository this task belongs to
statestringrequired
Current state of the task, derived from its most recent session
Allowed:queuedin_progresscompletedfailedidlewaiting_for_usertimed_outcancelled
session_countintegeroptional
Number of sessions in this task
artifactsarray<object>optional
Resources created by this task (PRs, branches, etc.)
archived_atstringoptional
Timestamp when the task was archived, null if not archived
updated_atstringoptional
Timestamp of the most recent update
created_atstringrequired
Timestamp when the task was created
custom_agentobjectoptional
Custom agent metadata associated with this task
sessionsarray<object>optional
Sessions associated with this task
400Problems parsing 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
404Resource not found
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: Problems parsing request. A 401 is returned: Authentication required. A 403 is returned: Insufficient permissions. A 404 is returned: Resource not found. A 422 is returned: Validation Failed.