Skip to content
forgit api docs

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:

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

Section titled “ Parameters ”

Query Parameters

Section titled “ 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)

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Tasks retrieved successfully

Media type application/json
object
tasks
required

List of tasks

Array<object>
object
id
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:

A GitHub user

object
id

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
id

The unique identifier of the user

integer format: int64
owner

The owner of the repository

object
id

The unique identifier of the user

integer format: int64
repository

The repository this task belongs to

object
id

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:

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

object
id
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
id

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
Example default 
{
  "tasks": [
    {
      "id": "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

Section titled “ Headers ”
Link
string

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

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

400

Section titled “ 400 ”

Bad request

Media type 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

Section titled “ 401 ”

Authentication required

Media type 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"
    }
  ]
}

403

Section titled “ 403 ”

Insufficient permissions

Media type 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"
    }
  ]
}

422

Section titled “ 422 ”

Validation Failed

Media type 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"
    }
  ]
}