---
title: "Start a task"
method: POST
path: "/agents/repos/{owner}/{repo}/tasks"
tags: ["agent-tasks"]
---

# Start a task

`POST /agents/repos/{owner}/{repo}/tasks`

> [!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:

* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)
* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)

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.

## Path parameters

- `owner` string, required
- `repo` string, required

## Request body

- object
  - `prompt` string, required — The user's prompt for the agent
  - `model` string — 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_agent` string — 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_request` boolean — Whether to create a PR.
  - `base_ref` string — Base ref for new branch/PR
  - `head_ref` string — 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 `201`

Task created successfully

- object
  - `id` string, required — Unique task identifier
  - `url` string — API URL for this task
  - `html_url` string — Web URL for this task
  - `name` string — Human-readable name derived from the task prompt
  - `creator` object — A GitHub user
    - `id` integer — The unique identifier of the user
  - `creator_type` 'user' | 'organization' — Type of the task creator
  - `user_collaborators` object[] — User objects of collaborators on this task
    - `id` integer — The unique identifier of the user
  - `owner` object — The owner of the repository
    - `id` integer — The unique identifier of the user
  - `repository` object — The repository this task belongs to
    - `id` integer — The unique identifier of the repository
  - `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_count` integer — Number of sessions in this task
  - `artifacts` object[] — Resources created by this task (PRs, branches, etc.)
    - `provider` 'github', required — Provider namespace
    - `type` 'pull' | 'branch', required — Type of artifact. Available Values: `pull`, `branch`.
    - `data` union, required — Resource data (shape depends on type)
      - object — A GitHub resource (pull request, issue, etc.)
        - `id` integer, required — GitHub resource ID
        - `global_id` string — GraphQL global ID
      - object — A Git branch reference
        - `head_ref` string, required — Head branch name
        - `base_ref` string, required — Base branch name
  - `archived_at` string, date-time, nullable — Timestamp when the task was archived, null if not archived
  - `updated_at` string, date-time — Timestamp of the most recent update
  - `created_at` string, date-time, required — Timestamp when the task was created
  - `custom_agent` object — Custom agent metadata associated with this task
    - `id` string — The custom agent's filename without the extension - for example, `performance-optimizer` for a `.github/agents/performance-optimizer.agent.md` custom agent.

## Other responses

- `400` — Problems parsing JSON
- `401` — Authentication required
- `403` — Insufficient permissions
- `422` — Validation Failed

---

[API](https://skmtc.net/github/apis/rest-api.md) · [All operations](https://skmtc.net/github/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/github/rest-api/versions/80850db290cd/schema)