---
title: "Get a task by ID"
method: GET
path: "/agents/tasks/{task_id}"
tags: ["agent-tasks"]
---

# Get a task by ID

`GET /agents/tasks/{task_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:

* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)
* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)

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.

## Path parameters

- `task_id` string, required

## Response `200`

Task retrieved successfully

- object
  - `id` string, required — Unique task identifier
  - `url` string — API URL for this task
  - `html_url` string — Web URL for this task
  - `name` string — Human-readable name derived from the task prompt
  - `creator` object — A GitHub user
    - `id` integer — The unique identifier of the user
  - `creator_type` 'user' | 'organization' — Type of the task creator
  - `user_collaborators` object[] — User objects of collaborators on this task
    - `id` integer — The unique identifier of the user
  - `owner` object — The owner of the repository
    - `id` integer — The unique identifier of the user
  - `repository` object — The repository this task belongs to
    - `id` integer — The unique identifier of the repository
  - `state` 'queued' | 'in_progress' | 'completed' | 'failed' | 'idle' | 'waiting_for_user' | 'timed_out' | 'cancelled', required — Current state of the task, derived from its most recent session
  - `session_count` integer — Number of sessions in this task
  - `artifacts` object[] — Resources created by this task (PRs, branches, etc.)
    - `provider` 'github', required — Provider namespace
    - `type` 'pull' | 'branch', required — Type of artifact. Available Values: `pull`, `branch`.
    - `data` union, required — Resource data (shape depends on type)
      - object — A GitHub resource (pull request, issue, etc.)
        - `id` integer, required — GitHub resource ID
        - `global_id` string — GraphQL global ID
      - object — A Git branch reference
        - `head_ref` string, required — Head branch name
        - `base_ref` string, required — Base branch name
  - `archived_at` string, date-time, nullable — Timestamp when the task was archived, null if not archived
  - `updated_at` string, date-time — Timestamp of the most recent update
  - `created_at` string, date-time, required — Timestamp when the task was created
  - `sessions` object[] — Sessions associated with this task
    - `id` string, required — Session ID
    - `name` string — Session name
    - `user` object — The user who created this session
      - `id` integer — The unique identifier of the user
    - `owner` object — The owner of the repository
      - `id` integer — The unique identifier of the user
    - `repository` object — The repository this session belongs to
      - `id` integer — The unique identifier of the repository
    - `task_id` string — Task ID this session belongs to
    - `state` 'queued' | 'in_progress' | 'completed' | 'failed' | 'idle' | 'waiting_for_user' | 'timed_out' | 'cancelled', required — Current state of a session
    - `created_at` string, date-time, required — Creation timestamp
    - `updated_at` string, date-time — Last update timestamp
    - `completed_at` string, date-time — Completion timestamp
    - `prompt` string — Content of the triggering event
    - `head_ref` string — Head branch name
    - `base_ref` string — Base branch name
    - `model` string — Model used for this session
    - `error` object — Error details for a failed session
      - `message` string — Error message

## Other responses

- `400` — Problems parsing request
- `401` — Authentication required
- `403` — Insufficient permissions
- `404` — Resource not found
- `422` — Validation Failed

## Changes

- **2026-05-05** (2022-11-28) `e931c3581f42` — 1 info
  - endpoint added
- **2026-04-14** (2022-11-28) `4da3647e057c` — 1 breaking
  - api path removed without deprecation
- **2026-04-09** (2022-11-28) `a1ce348995ab` — 2 info
  - added `subschema #1, subschema #2` to the response body `allOf` list for the response status `200`
  - removed `subschema #1, subschema #2` from the response body `allOf` list for the response status `200`
- **2026-04-02** (2022-11-28) `c6dda6cbc43e` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/github/apis/rest/changes/agents/tasks/:task_id/get.md)

---

[API](https://skmtc.dev/github/apis/rest.md) · [All operations](https://skmtc.dev/github/apis/rest/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/github/rest/revisions/4c55d6805a6a/schema)