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

# Get a task by repo

`GET /agents/repos/{owner}/{repo}/tasks/{task_id}`

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

Returns a task by ID scoped to an owner/repo path

**Fine-grained access tokens for "Get a task by repo"**

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

* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/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/enterprise-cloud@latest/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

- `owner` string, required
- `repo` string, required
- `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
  - `custom_agent` object — Custom agent metadata associated with this task
    - `id` string — The custom agent's filename without the extension - for example, `performance-optimizer` for a `.github/agents/performance-optimizer.agent.md` custom agent.
  - `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
    - `usage` object — Structured information about billing units consumed by the session.
      - `type` 'ai_credits' | 'premium_requests', required — Billing unit used for this session. New sessions since June 1, 2026 use `ai_credits`, but older sessions use `premium_requests`.
      - `amount` number, double, required — Number of billing units used by this session. When the `type` is `ai_credits`, the value is a whole number, expressed in nano units. When presenting this to a human, divide by 1,000,000,000 and round to one decimal place. When aggregating (for example, summing usage across sessions), sum the nano values first, and divide once at the end before presenting to a human to avoid losing precision. When the `type` is `premium_requests`, the value may be fractional (for example `1.5`).
    - `error` object — Error details for a failed session
      - `message` string — Error message

## Other responses

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

---

[API](https://skmtc.net/github/apis/github-v3-rest-api-3.md) · [All operations](https://skmtc.net/github/apis/github-v3-rest-api-3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/github/github-v3-rest-api-3/versions/dc0584ac4e13/schema)