Skip to content
forgit api docs

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:

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 ”

Path Parameters

Section titled “ Path Parameters ”
task_id
required
string

The unique identifier of the task.

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Task retrieved successfully

Media type application/json
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
sessions

Sessions associated with this task

Array<object>

Full session details within a task

object
id
required

Session ID

string
name

Session name

string
user

The user who created this session

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 session belongs to

object
id

The unique identifier of the repository

integer format: int64
task_id

Task ID this session belongs to

string
state
required

Current state of a session

string
Allowed values: queued in_progress completed failed idle waiting_for_user timed_out cancelled
created_at
required

Creation timestamp

string format: date-time
updated_at

Last update timestamp

string format: date-time
completed_at

Completion timestamp

string format: date-time
prompt

Content of the triggering event

string
head_ref

Head branch name

string
base_ref

Base branch name

string
model

Model used for this session

string
usage

Structured information about billing units consumed by the session.

object
type
required

Billing unit used for this session. New sessions since June 1, 2026 use ai_credits, but older sessions use premium_requests.

string
Allowed values: ai_credits premium_requests
amount
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).

number format: double
error

Error details for a failed session

object
message

Error message

string
Examples
Example default 
{
  "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",
  "sessions": [
    {
      "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Fix the login button on the homepage",
      "user": {
        "id": 1
      },
      "owner": {
        "id": 1
      },
      "repository": {
        "id": 1296269
      },
      "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "state": "completed",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T01:00:00Z",
      "completed_at": "2025-01-01T01:00:00Z",
      "prompt": "Fix the login button on the homepage",
      "head_ref": "copilot/fix-1",
      "base_ref": "main",
      "model": "claude-sonnet-4.6"
    }
  ]
}

400

Section titled “ 400 ”

Problems parsing 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"
    }
  ]
}

404

Section titled “ 404 ”

Resource not found

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