{"meta":{"title":"REST API endpoints for agent tasks","intro":"Use the REST API to start and manage Copilot cloud agent tasks","product":"REST API","breadcrumbs":[{"href":"/en/enterprise-cloud@latest/rest","title":"REST API"},{"href":"/en/enterprise-cloud@latest/rest/agent-tasks","title":"Agent tasks"},{"href":"/en/enterprise-cloud@latest/rest/agent-tasks/agent-tasks","title":"Agent tasks"}],"documentType":"article"},"body":"# REST API endpoints for agent tasks\n\nUse the REST API to start and manage Copilot cloud agent tasks\n\n> [!NOTE]\n> Most endpoints use `Authorization: Bearer <YOUR-TOKEN>` and `Accept: application/vnd.github+json` headers, plus `X-GitHub-Api-Version: 2026-03-10`. Curl examples below omit these standard headers for brevity.\n\n## List tasks for repository\n\n```\nGET /agents/repos/{owner}/{repo}/tasks\n```\n\nNote\n\nThis endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\nFine-grained access tokens for \"List tasks for repository\"\nThis endpoint works with the following fine-grained token types:\n\nGitHub App user access tokens\nFine-grained personal access tokens\n\nThe fine-grained token must have the following permission set:\n\n\"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`owner`** (string) (required)\n  The account owner of the repository. The name is not case sensitive.\n\n- **`repo`** (string) (required)\n  The name of the repository. The name is not case sensitive.\n\n- **`per_page`** (integer)\n  The number of results per page (max 100).\n  Default: `30`\n\n- **`page`** (integer)\n  The page number of the results to fetch.\n  Default: `1`\n\n- **`sort`** (string)\n  The field to sort results by. Can be updated_at or created_at.\n  Default: `updated_at`\n  Can be one of: `updated_at`, `created_at`\n\n- **`direction`** (string)\n  The direction to sort results. Can be asc or desc.\n  Default: `desc`\n  Can be one of: `asc`, `desc`\n\n- **`state`** (string)\n  Comma-separated list of task states to filter by. Can be any combination of: queued, in_progress, completed, failed, idle, waiting_for_user, timed_out, cancelled.\n\n- **`is_archived`** (boolean)\n  Filter by archived status. When true, returns only archived tasks. When false or omitted, returns only non-archived tasks. Defaults to false.\n  Default: `false`\n\n- **`since`** (string)\n  Only show tasks updated at or after this time (ISO 8601 timestamp)\n\n- **`creator_id`** (array)\n  Filter tasks by creator user ID. Accepts one or more user IDs.\n\n### HTTP response status codes\n\n- **200** - Tasks retrieved successfully\n\n- **400** - Bad request\n\n- **401** - Authentication required\n\n- **403** - Insufficient permissions\n\n- **404** - Resource not found\n\n- **422** - Validation Failed\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/agents/repos/OWNER/REPO/tasks\n```\n\n**Response schema (Status: 200):**\n\n* `tasks`: required, array of objects:\n  * `id`: required, string\n  * `url`: string\n  * `html_url`: string\n  * `name`: string\n  * `creator`: one of:\n    * **object**\n      * `id`: integer, format: int64\n  * `creator_type`: string, enum: `user`, `organization`\n  * `user_collaborators`: array of objects:\n    * `id`: integer, format: int64\n  * `owner`: object:\n    * `id`: integer, format: int64\n  * `repository`: object:\n    * `id`: integer, format: int64\n  * `state`: required, string, enum: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`\n  * `session_count`: integer, format: int32\n  * `artifacts`: array of objects:\n    * `provider`: required, string, enum: `github`\n    * `type`: required, string, enum: `pull`, `branch`\n    * `data`: required, one of:\n      * **object**\n        * `id`: required, integer, format: int64\n        * `global_id`: string\n      * **object**\n        * `head_ref`: required, string\n        * `base_ref`: required, string\n  * `archived_at`: string or null, format: date-time\n  * `updated_at`: string, format: date-time\n  * `created_at`: required, string, format: date-time\n  * `custom_agent`: object:\n    * `id`: string\n* `total_active_count`: integer, format: int32\n* `total_archived_count`: integer, format: int32\n\n## Start a task\n\n```\nPOST /agents/repos/{owner}/{repo}/tasks\n```\n\nNote\n\nThis endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\nFine-grained access tokens for \"Start a task\"\nThis endpoint works with the following fine-grained token types:\n\nGitHub App user access tokens\nFine-grained personal access tokens\n\nThe fine-grained token must have the following permission set:\n\n\"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`owner`** (string) (required)\n  The account owner of the repository. The name is not case sensitive.\n\n- **`repo`** (string) (required)\n  The name of the repository. The name is not case sensitive.\n\n#### Body parameters\n\n- **`prompt`** (string) (required)\n  The user's prompt for the agent\n\n- **`model`** (string)\n  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\n\n- **`custom_agent`** (string)\n  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.\n\n- **`create_pull_request`** (boolean)\n  Whether to create a PR.\n  Default: `false`\n\n- **`base_ref`** (string)\n  Base ref for new branch/PR\n\n- **`head_ref`** (string)\n  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.\n\n### HTTP response status codes\n\n- **201** - Task created successfully\n\n- **400** - Problems parsing JSON\n\n- **401** - Authentication required\n\n- **403** - Insufficient permissions\n\n- **422** - Validation Failed\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X POST \\\n  https://api.github.com/agents/repos/OWNER/REPO/tasks \\\n  -d '{\n  \"prompt\": \"Fix the login button on the homepage\",\n  \"base_ref\": \"main\"\n}'\n```\n\n**Response schema (Status: 201):**\n\n* `id`: required, string\n* `url`: string\n* `html_url`: string\n* `name`: string\n* `creator`: one of:\n  * **object**\n    * `id`: integer, format: int64\n* `creator_type`: string, enum: `user`, `organization`\n* `user_collaborators`: array of objects:\n  * `id`: integer, format: int64\n* `owner`: object:\n  * `id`: integer, format: int64\n* `repository`: object:\n  * `id`: integer, format: int64\n* `state`: required, string, enum: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`\n* `session_count`: integer, format: int32\n* `artifacts`: array of objects:\n  * `provider`: required, string, enum: `github`\n  * `type`: required, string, enum: `pull`, `branch`\n  * `data`: required, one of:\n    * **object**\n      * `id`: required, integer, format: int64\n      * `global_id`: string\n    * **object**\n      * `head_ref`: required, string\n      * `base_ref`: required, string\n* `archived_at`: string or null, format: date-time\n* `updated_at`: string, format: date-time\n* `created_at`: required, string, format: date-time\n* `custom_agent`: object:\n  * `id`: string\n\n#### Task with a custom agent\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X POST \\\n  https://api.github.com/agents/repos/OWNER/REPO/tasks \\\n  -d '{\n  \"prompt\": \"Fix the login button on the homepage\",\n  \"base_ref\": \"main\",\n  \"custom_agent\": \"my-custom-agent\"\n}'\n```\n\n**Response schema (Status: 201):**\n\n* `id`: required, string\n* `url`: string\n* `html_url`: string\n* `name`: string\n* `creator`: one of:\n  * **object**\n    * `id`: integer, format: int64\n* `creator_type`: string, enum: `user`, `organization`\n* `user_collaborators`: array of objects:\n  * `id`: integer, format: int64\n* `owner`: object:\n  * `id`: integer, format: int64\n* `repository`: object:\n  * `id`: integer, format: int64\n* `state`: required, string, enum: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`\n* `session_count`: integer, format: int32\n* `artifacts`: array of objects:\n  * `provider`: required, string, enum: `github`\n  * `type`: required, string, enum: `pull`, `branch`\n  * `data`: required, one of:\n    * **object**\n      * `id`: required, integer, format: int64\n      * `global_id`: string\n    * **object**\n      * `head_ref`: required, string\n      * `base_ref`: required, string\n* `archived_at`: string or null, format: date-time\n* `updated_at`: string, format: date-time\n* `created_at`: required, string, format: date-time\n* `custom_agent`: object:\n  * `id`: string\n\n## Get a task by repo\n\n```\nGET /agents/repos/{owner}/{repo}/tasks/{task_id}\n```\n\nNote\n\nThis endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\nFine-grained access tokens for \"Get a task by repo\"\nThis endpoint works with the following fine-grained token types:\n\nGitHub App user access tokens\nFine-grained personal access tokens\n\nThe fine-grained token must have the following permission set:\n\n\"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`owner`** (string) (required)\n  The account owner of the repository. The name is not case sensitive.\n\n- **`repo`** (string) (required)\n  The name of the repository. The name is not case sensitive.\n\n- **`task_id`** (string) (required)\n  The unique identifier of the task.\n\n### HTTP response status codes\n\n- **200** - Task retrieved successfully\n\n- **400** - Bad request\n\n- **401** - Authentication required\n\n- **403** - Insufficient permissions\n\n- **404** - Resource not found\n\n- **422** - Validation Failed\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/agents/repos/OWNER/REPO/tasks/TASK_ID\n```\n\n**Response schema (Status: 200):**\n\n* all of:\n  * **object**\n    * `id`: required, string\n    * `url`: string\n    * `html_url`: string\n    * `name`: string\n    * `creator`: one of:\n      * **object**\n        * `id`: integer, format: int64\n    * `creator_type`: string, enum: `user`, `organization`\n    * `user_collaborators`: array of objects:\n      * `id`: integer, format: int64\n    * `owner`: object:\n      * `id`: integer, format: int64\n    * `repository`: object:\n      * `id`: integer, format: int64\n    * `state`: required, string, enum: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`\n    * `session_count`: integer, format: int32\n    * `artifacts`: array of objects:\n      * `provider`: required, string, enum: `github`\n      * `type`: required, string, enum: `pull`, `branch`\n      * `data`: required, one of:\n        * **object**\n          * `id`: required, integer, format: int64\n          * `global_id`: string\n        * **object**\n          * `head_ref`: required, string\n          * `base_ref`: required, string\n    * `archived_at`: string or null, format: date-time\n    * `updated_at`: string, format: date-time\n    * `created_at`: required, string, format: date-time\n    * `custom_agent`: object:\n      * `id`: string\n  * **object**\n    * `sessions`: array of objects:\n      * `id`: required, string\n      * `name`: string\n      * `user`: object:\n        * `id`: integer, format: int64\n      * `owner`: object:\n        * `id`: integer, format: int64\n      * `repository`: object:\n        * `id`: integer, format: int64\n      * `task_id`: string\n      * `state`: required, string, enum: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`\n      * `created_at`: required, string, format: date-time\n      * `updated_at`: string, format: date-time\n      * `completed_at`: string, format: date-time\n      * `prompt`: string\n      * `head_ref`: string\n      * `base_ref`: string\n      * `model`: string\n      * `usage`: object:\n        * `type`: required, string, enum: `ai_credits`, `premium_requests`\n        * `amount`: required, number, format: double\n      * `error`: object:\n        * `message`: string\n\n## List tasks\n\n```\nGET /agents/tasks\n```\n\nNote\n\nThis endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\nFine-grained access tokens for \"List tasks\"\nThis endpoint works with the following fine-grained token types:\n\nGitHub App user access tokens\nFine-grained personal access tokens\n\nThe fine-grained token must have the following permission set:\n\n\"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`per_page`** (integer)\n  The number of results per page (max 100).\n  Default: `30`\n\n- **`page`** (integer)\n  The page number of the results to fetch.\n  Default: `1`\n\n- **`sort`** (string)\n  The field to sort results by. Can be updated_at or created_at.\n  Default: `updated_at`\n  Can be one of: `updated_at`, `created_at`\n\n- **`direction`** (string)\n  The direction to sort results. Can be asc or desc.\n  Default: `desc`\n  Can be one of: `asc`, `desc`\n\n- **`state`** (string)\n  Comma-separated list of task states to filter by. Can be any combination of: queued, in_progress, completed, failed, idle, waiting_for_user, timed_out, cancelled.\n\n- **`is_archived`** (boolean)\n  Filter by archived status. When true, returns only archived tasks. When false or omitted, returns only non-archived tasks. Defaults to false.\n  Default: `false`\n\n- **`since`** (string)\n  Only show tasks updated at or after this time (ISO 8601 timestamp)\n\n### HTTP response status codes\n\n- **200** - Tasks retrieved successfully\n\n- **400** - Bad request\n\n- **401** - Authentication required\n\n- **403** - Insufficient permissions\n\n- **422** - Validation Failed\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/agents/tasks\n```\n\n**Response schema (Status: 200):**\n\nSame response schema as [List tasks for repository](#list-tasks-for-repository).\n\n## Get a task by ID\n\n```\nGET /agents/tasks/{task_id}\n```\n\nNote\n\nThis endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\nFine-grained access tokens for \"Get a task by ID\"\nThis endpoint works with the following fine-grained token types:\n\nGitHub App user access tokens\nFine-grained personal access tokens\n\nThe fine-grained token must have the following permission set:\n\n\"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`task_id`** (string) (required)\n  The unique identifier of the task.\n\n### HTTP response status codes\n\n- **200** - Task retrieved successfully\n\n- **400** - Problems parsing request\n\n- **401** - Authentication required\n\n- **403** - Insufficient permissions\n\n- **404** - Resource not found\n\n- **422** - Validation Failed\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/agents/tasks/TASK_ID\n```\n\n**Response schema (Status: 200):**\n\nSame response schema as [Get a task by repo](#get-a-task-by-repo)."}