agent-tasks

Start a task

Changed on

[!NOTE] This endpoint is in public preview and is subject to change.

Starts a new Copilot cloud agent task for a repository.

This endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.

Fine-grained access tokens for "Start a task"

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 and write)

GitHub App installation access tokens are not supported for this endpoint.

post/agents/repos/{owner}/{repo}/tasks

Request

  • Base URL: https://api.github.com
  • URL: https://api.github.com/agents/repos/{owner}/{repo}/tasks
  • Auth: none declared

Path parameters

ownerstring required

The account owner of the repository. The name is not case sensitive.

repostring required

The name of the repository. The name is not case sensitive.

Request body

promptstring required

The user's prompt for the agent

modelstring

The model to use for this task. The allowed models may change over time and depend on the user's GitHub Copilot plan and organization policies. Currently supported values: claude-sonnet-4.6, claude-opus-4.6, gpt-5.2-codex, gpt-5.3-codex, gpt-5.4, claude-sonnet-4.5, claude-opus-4.5

custom_agentstring

Optional identifier for a custom agent to use for this task. Use the custom agent's filename without the extension - for example, for a .github/agents/performance-optimizer.agent.md custom agent, use performance-optimizer.

create_pull_requestboolean

Whether to create a PR.

base_refstring

Base ref for new branch/PR

head_refstring

Head ref for existing branch/PR. If provided with base_ref, the agent looks up open PR context for head_ref targeting base_ref and commits to head_ref instead of creating a new branch.

Response

Task created successfully

idstring required

Unique task identifier

urlstring

API URL for this task

html_urlstring

Web URL for this task

namestring

Human-readable name derived from the task prompt

creator_type'user' | 'organization'

Type of the task creator

state'queued' | 'in_progress' | 'completed' | 'failed' | 'idle' | 'waiting_for_user' | 'timed_out' | 'cancelled' required

Current state of the task, derived from its most recent session

session_countinteger

Number of sessions in this task

archived_atstring date-time nullable

Timestamp when the task was archived, null if not archived

updated_atstring date-time

Timestamp of the most recent update

created_atstring date-time required

Timestamp when the task was created

Changes

  • 2022-11-2837bb7bcfab4bRevision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

  • 2022-11-281c7970c7bd6bRevision changes
    • info

      added the new optional request property