GitHub: Agent tasks schemas
5 GitHub schemas with complete fields and constraints.
← Agent tasks operations · All schemas
Get a task by ID — response body — creator_type: user, organization
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
archived_at | JSON | Optional | |
archived_at (anyOf 1) | string | Alternative | Timestamp when the task was archived, null if not archived Format: date-time |
archived_at (anyOf 2) | null | Alternative | |
artifacts | array | Optional | Resources created by this task (PRs, branches, etc.) |
artifacts[] | Model | Each item | Expand Start a task — response body — artifacts item |
created_at | string | Required within parent | Timestamp when the task was created Format: date-time |
creator | JSON | Optional | The entity who created this task |
creator (anyOf 1) | object | Alternative | A GitHub user |
creator (anyOf 1).id | JSON | Optional | |
creator (anyOf 1).id (anyOf 1) | integer | Alternative | The unique identifier of the user Format: int64 |
creator (anyOf 1).id (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
creator_type | string | Optional | Type of the task creator Known values: user, organization |
custom_agent | object | Optional | Custom agent metadata associated with this task |
custom_agent.id | string | Optional | The custom agent's filename without the extension - for example, `performance-optimizer` for a `.github/agents/performance-optimizer.agent.md` custom agent. |
html_url | string | Optional | Web URL for this task |
id | string | Required within parent | Unique task identifier |
name | string | Optional | Human-readable name derived from the task prompt |
owner | object | Optional | The owner of the repository |
owner.id | JSON | Optional | |
owner.id (anyOf 1) | integer | Alternative | The unique identifier of the user Format: int64 |
owner.id (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
repository | object | Optional | The repository this task belongs to |
repository.id | JSON | Optional | |
repository.id (anyOf 1) | integer | Alternative | The unique identifier of the repository Format: int64 |
repository.id (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
session_count | JSON | Optional | |
session_count (anyOf 1) | integer | Alternative | Number of sessions in this task Format: int32 |
session_count (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
state | string | Required within parent | Current state of the task, derived from its most recent session Known values: queued, in_progress, completed, failed, idle, waiting_for_user, timed_out, cancelled |
updated_at | string | Optional | Timestamp of the most recent update Format: date-time |
url | string | Optional | API URL for this task |
user_collaborators | array | Optional | User objects of collaborators on this task |
user_collaborators[] | object | Each item | A GitHub user |
user_collaborators[].id | JSON | Optional | |
user_collaborators[].id (anyOf 1) | integer | Alternative | The unique identifier of the user Format: int64 |
user_collaborators[].id (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Referenced models: Start a task — response body — artifacts item
Get a task by ID — response body — sessions
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
sessions | array | Optional | Sessions associated with this task |
sessions[] | Model | Each item | Expand Get a task by ID — response body — sessions sessions item |
Referenced models: Get a task by ID — response body — sessions sessions item
Get a task by ID — response body — sessions sessions item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Full session details within a task |
base_ref | string | Optional | Base branch name |
completed_at | string | Optional | Completion timestamp Format: date-time |
created_at | string | Required within parent | Creation timestamp Format: date-time |
error | object | Optional | Error details for a failed session |
error.message | string | Optional | Error message |
head_ref | string | Optional | Head branch name |
id | string | Required within parent | Session ID |
model | string | Optional | Model used for this session |
name | string | Optional | Session name |
owner | object | Optional | The owner of the repository |
owner.id | JSON | Optional | |
owner.id (anyOf 1) | integer | Alternative | The unique identifier of the user Format: int64 |
owner.id (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
prompt | string | Optional | Content of the triggering event |
repository | object | Optional | The repository this session belongs to |
repository.id | JSON | Optional | |
repository.id (anyOf 1) | integer | Alternative | The unique identifier of the repository Format: int64 |
repository.id (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
state | string | Required within parent | Current state of a session Known values: queued, in_progress, completed, failed, idle, waiting_for_user, timed_out, cancelled |
task_id | string | Optional | Task ID this session belongs to |
updated_at | string | Optional | Last update timestamp Format: date-time |
usage | Model | Optional | Expand Get a task by ID — response body — sessions sessions item usage |
user | object | Optional | The user who created this session |
user.id | JSON | Optional | |
user.id (anyOf 1) | integer | Alternative | The unique identifier of the user Format: int64 |
user.id (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Referenced models: Get a task by ID — response body — sessions sessions item usage
Get a task by ID — response body — sessions sessions item usage
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Structured information about billing units consumed by the session. |
amount | JSON | Required within parent | |
amount (anyOf 1) | number | Alternative | 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`). Format: double |
amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
type | string | Required within parent | Billing unit used for this session. New sessions since June 1, 2026 use `ai_credits`, but older sessions use `premium_requests`. Known values: ai_credits, premium_requests |
Start a task — response body — artifacts item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A resource generated by the task |
data | JSON | Required within parent | Resource data (shape depends on type) |
data (anyOf 1) | object | Alternative | A GitHub resource (pull request, issue, etc.) |
data (anyOf 1).global_id | string | Optional | GraphQL global ID |
data (anyOf 1).id | JSON | Required within parent | |
data (anyOf 1).id (anyOf 1) | integer | Alternative | GitHub resource ID Format: int64 |
data (anyOf 1).id (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
data (anyOf 2) | object | Alternative | A Git branch reference |
data (anyOf 2).base_ref | string | Required within parent | Base branch name |
data (anyOf 2).head_ref | string | Required within parent | Head branch name |
provider | string | Required within parent | Provider namespace Known values: github |
type | string | Required within parent | Type of artifact. Available Values: `pull`, `branch`. Known values: pull, branch |