---
title: "List tasks"
method: GET
path: "/agents/tasks"
tags: ["agent-tasks"]
---

# List tasks

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

* [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.

## Query parameters

- `per_page` integer
- `page` integer
- `sort` 'updated_at' | 'created_at'
- `direction` 'asc' | 'desc'
- `state` string
- `is_archived` boolean
- `since` string, date-time

## Response `200`

Tasks retrieved successfully

- object
  - `tasks` object[], required — List of tasks
    - `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
  - `total_active_count` integer — Total count of active (non-archived) tasks
  - `total_archived_count` integer — Total count of archived tasks

## Other responses

- `400` — Bad request
- `401` — Authentication required
- `403` — Insufficient permissions
- `422` — Validation Failed

## Changes

- **2026-05-05** `dcb9a574778b` — 1 info
  - endpoint added
- **2026-04-14** `3e123249999a` — 1 breaking
  - api path removed without deprecation
- **2026-04-09** `bc41f0958ba7` — 1 breaking, 1 warning, 2 info
  - added `subschema #1, subschema #2` to the `tasks/items/artifacts/items/data` response property `oneOf` list for the response status `200`
  - added the new `pull` enum value to the `tasks/items/artifacts/items/type` response property for the response status `200`
  - removed the `github_resource` enum value from the `tasks/items/artifacts/items/type` response property for the response status `200`
  - removed `subschema #1, subschema #2` from the `tasks/items/artifacts/items/data` response property `oneOf` list for the response status `200`
- **2026-04-02** `b0fdd71dd714` — 1 breaking
  - for the `query` request parameter `is_archived`, default value `false` was added
- **2026-04-02** `f46a0dd461fb` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/github/apis/enterprise-cloud/changes/agents/tasks/get.md)

---

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