GitHub: List tasks

← Agent tasks operations · Get started

Operation github.agent_tasks_list_tasks

Provider route: GET /agents/tasks. 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"]["agentTasksListTasks"]>[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.agentTasksListTasks(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_list_tasks(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Optional	Additional keys: not allowed
query.per_page	integer	Optional	Default: 30 Maximum: 100 Minimum: 1
query.page	integer	Optional	Default: 1 Minimum: 1
query.sort	string	Optional	Default: updated_at One of: updated_at, created_at
query.direction	string	Optional	Default: desc One of: asc, desc
query.state	string	Optional
query.is_archived	boolean	Optional	Default: false
query.since	string	Optional	Format: date-time

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
$	object	Root
tasks	array	Required within parent	List of tasks
tasks[]	Model	Each item	Expand Get a task by ID — response body — creator_type: user, organization
total_active_count	JSON	Optional
total_active_count (anyOf 1)	integer	Alternative	Total count of active (non-archived) tasks Format: int32
total_active_count (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
total_archived_count	JSON	Optional
total_archived_count (anyOf 1)	integer	Alternative	Total count of archived tasks Format: int32
total_archived_count (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

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

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

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

Policy, approvals and errors

SDK function policy ID: github.agent_tasks_list_tasks. Catalog operation: agent-tasks/list-tasks. 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