List tasks for repository

GET

/agents/repos/{owner}/{repo}/tasks

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

Returns a list of tasks for a specific repository

Fine-grained access tokens for “List tasks for repository”

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.

API method documentation

Parameters

Path Parameters

owner

required

string

The account owner of the repository. The name is not case sensitive.

repo

required

string

The name of the repository. The name is not case sensitive.

Query Parameters

per_page

integer

default: 30 >= 1 <= 100

The number of results per page (max 100).

page

integer

default: 1 >= 1

The page number of the results to fetch.

sort

string

default: updated_at

Allowed values: updated_at created_at

The field to sort results by. Can be updated_at or created_at.

direction

string

default: desc

Allowed values: asc desc

The direction to sort results. Can be asc or desc.

state

string

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_archived

boolean

Filter by archived status. When true, returns only archived tasks. When false or omitted, returns only non-archived tasks. Defaults to false.

since

string format: date-time

Only show tasks updated at or after this time (ISO 8601 timestamp)

creator_id

Array<integer>

Filter tasks by creator user ID. Accepts one or more user IDs.

Responses

200

Tasks retrieved successfully

application/json

object

tasks

required

List of tasks

Array<object>

object

required

Unique task identifier

string

url

API URL for this task

string

html_url

Web URL for this task

string

name

Human-readable name derived from the task prompt

string

creator

One of:

object

A GitHub user

object

The unique identifier of the user

integer format: int64

creator_type

Type of the task creator

string

Allowed values: user organization

user_collaborators

User objects of collaborators on this task

Array<object>

A GitHub user

object

The unique identifier of the user

integer format: int64

owner

The owner of the repository

object

The unique identifier of the user

integer format: int64

repository

The repository this task belongs to

object

The unique identifier of the repository

integer format: int64

state

required

Current state of the task, derived from its most recent session

string

Allowed values: queued in_progress completed failed idle waiting_for_user timed_out cancelled

session_count

Number of sessions in this task

integer format: int32

artifacts

Resources created by this task (PRs, branches, etc.)

Array<object>

A resource generated by the task

object

provider

required

Provider namespace

string

Allowed values: github

type

required

Type of artifact. Available Values: pull, branch.

string

Allowed values: pull branch

data

required

One of:

object
object

A GitHub resource (pull request, issue, etc.)

object

required

GitHub resource ID

integer format: int64

global_id

GraphQL global ID

string

archived_at

Timestamp when the task was archived, null if not archived

string format: date-time

nullable

updated_at

Timestamp of the most recent update

string format: date-time

created_at

required

Timestamp when the task was created

string format: date-time

custom_agent

Custom agent metadata associated with this task

object

The custom agent’s filename without the extension - for example, performance-optimizer for a .github/agents/performance-optimizer.agent.md custom agent.

string

total_active_count

Total count of active (non-archived) tasks

integer format: int32

total_archived_count

Total count of archived tasks

integer format: int32

Examples

default

{
  "tasks": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Fix the login button on the homepage",
      "creator": {
        "id": 1
      },
      "creator_type": "user",
      "owner": {
        "id": 1
      },
      "repository": {
        "id": 1296269
      },
      "state": "completed",
      "session_count": 1,
      "artifacts": [
        {
          "provider": "github",
          "type": "pull",
          "data": {
            "id": 42
          }
        }
      ],
      "archived_at": null,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T01:00:00Z"
    }
  ]
}

Headers

Link

string

Pagination links. Contains rel=“first” (always), rel=“prev” (when current page > 1), rel=“next” (when more pages exist), and rel=“last” (when on the final page).

Example

<https://api.github.com/agents/repos/{owner}/{repo}/tasks?page=2&per_page=30>; rel="next", <https://api.github.com/agents/repos/{owner}/{repo}/tasks?page=1&per_page=30>; rel="first"

400

Bad request

application/json

Structured error response following GitHub REST API conventions. For 422 Unprocessable Entity the errors array contains validation details; for other error status codes only message and documentation_url are returned.

object

message

required

Summary message (e.g. “Validation Failed”, “Not Found”)

string

errors

List of validation errors (present only for 422 responses)

Array<object>

A single validation error

object

code

required

Machine-readable error code

string

Allowed values: missing missing_field invalid already_exists unprocessable custom

message

Human-readable message (populated when code is “custom”)

string

documentation_url

required

URL to relevant API documentation

string

Example

{
  "errors": [
    {
      "code": "missing"
    }
  ]
}

401

Authentication required

application/json

object

message

required

Summary message (e.g. “Validation Failed”, “Not Found”)

string

errors

List of validation errors (present only for 422 responses)

Array<object>

A single validation error

object

code

required

Machine-readable error code

string

Allowed values: missing missing_field invalid already_exists unprocessable custom

message

Human-readable message (populated when code is “custom”)

string

documentation_url

required

URL to relevant API documentation

string

Example

{
  "errors": [
    {
      "code": "missing"
    }
  ]
}

403

Insufficient permissions

application/json

object

message

required

Summary message (e.g. “Validation Failed”, “Not Found”)

string

errors

List of validation errors (present only for 422 responses)

Array<object>

A single validation error

object

code

required

Machine-readable error code

string

Allowed values: missing missing_field invalid already_exists unprocessable custom

message

Human-readable message (populated when code is “custom”)

string

documentation_url

required

URL to relevant API documentation

string

Example

{
  "errors": [
    {
      "code": "missing"
    }
  ]
}

404

Resource not found

application/json

object

message

required

Summary message (e.g. “Validation Failed”, “Not Found”)

string

errors

List of validation errors (present only for 422 responses)

Array<object>

A single validation error

object

code

required

Machine-readable error code

string

Allowed values: missing missing_field invalid already_exists unprocessable custom

message

Human-readable message (populated when code is “custom”)

string

documentation_url

required

URL to relevant API documentation

string

Example

{
  "errors": [
    {
      "code": "missing"
    }
  ]
}

422

Validation Failed

application/json

object

message

required

Summary message (e.g. “Validation Failed”, “Not Found”)

string

errors

List of validation errors (present only for 422 responses)

Array<object>

A single validation error

object

code

required

Machine-readable error code

string

Allowed values: missing missing_field invalid already_exists unprocessable custom

message

Human-readable message (populated when code is “custom”)

string

documentation_url

required

URL to relevant API documentation

string

Example

{
  "errors": [
    {
      "code": "missing"
    }
  ]
}