GitHub: Get a task by ID

← Agent tasks operations · Get started

Operation github.agent_tasks_get_task_by_id

Provider route: GET /agents/tasks/{task_id}. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/github with npm, or alter-sdk-github with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { GitHubIntegration } from "@alter-ai/github";

async function execute(input: Parameters<GitHubIntegration["agentTasks"]["agentTasksGetTaskById"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new GitHubIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.agentTasks.agentTasksGetTaskById(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_github import GitHubIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = GitHubIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.agent_tasks.agent_tasks_get_task_by_id(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.task_id	string	Required within parent

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	JSON	Root
$ (allOf 1)	Model	All variants apply	Expand Get a task by ID — response body — creator_type: user, organization
$ (allOf 2)	Model	All variants apply	Expand Get a task by ID — response body — sessions

Referenced models: Get a task by ID — response body — sessions, Get a task by ID — response body — creator_type: user, organization

Schemas

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 — 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 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

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

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

Policy, approvals and errors

SDK function policy ID: github.agent_tasks_get_task_by_id. Catalog operation: agent-tasks/get-task-by-id. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"X-GitHub-Api-Version": "2026-03-10", "User-Agent": "Alter", "Accept": "application/vnd.github+json"}

Official provider source