代理任务的 REST API 终结点

List tasks for repository

Note

This endpoint is in public preview and is subject to change.

Returns a list of tasks for a specific repository

Fine-grained access tokens for "List tasks for repository"

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)

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

“”List tasks for repository 的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`owner` string 必须 The account owner of the repository. The name is not case sensitive.
`repo` string 必须 The name of the repository. The name is not case sensitive.

查询参数
名称, 类型, 说明
`per_page` integer The number of results per page (max 100). 默认: `30`
`page` integer The page number of the results to fetch. 默认: `1`
`sort` string The field to sort results by. Can be `updated_at` or `created_at`. 默认: `updated_at` 可以是以下选项之一: `updated_at`, `created_at`
`direction` string The direction to sort results. Can be `asc` or `desc`. 默认: `desc` 可以是以下选项之一: `asc`, `desc`
`state` string 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`.
`is_archived` boolean Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`. 默认: `false`
`since` string Only show tasks updated at or after this time (ISO 8601 timestamp)
`creator_id` array Filter tasks by creator user ID. Accepts one or more user IDs.

“List tasks for repository”的 HTTP 响应状态代码

状态代码	说明
`200`	Tasks retrieved successfully
`400`	Bad request
`401`	Authentication required
`403`	Insufficient permissions
`404`	Resource not found
`422`	Validation Failed

“List tasks for repository”的代码示例

请求示例

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

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/repos/OWNER/REPO/tasks

Tasks retrieved successfully

Status: 200

{
  "tasks": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Fix the login button on the homepage",
      "creator": {
        "id": 1
      },
      "creator_type": "user",
      "owner": {
        "id": 1
      },
      "repository": {
        "id": 1296269
      },
      "state": "completed",
      "session_count": 1,
      "artifacts": [
        {
          "provider": "github",
          "type": "pull",
          "data": {
            "id": 42
          }
        }
      ],
      "archived_at": null,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T01:00:00Z"
    }
  ]
}

Start a task

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.

“”Start a task 的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`owner` string 必须 The account owner of the repository. The name is not case sensitive.
`repo` string 必须 The name of the repository. The name is not case sensitive.

主体参数
名称, 类型, 说明
`prompt` string 必须 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. 默认: `false`
`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.

“Start a task”的 HTTP 响应状态代码

状态代码	说明
`201`	Task created successfully
`400`	Problems parsing JSON
`401`	Authentication required
`403`	Insufficient permissions
`422`	Validation Failed

“Start a task”的代码示例

请求示例

Select the example type

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

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/repos/OWNER/REPO/tasks \
  -d '{"prompt":"Fix the login button on the homepage","base_ref":"main"}'

Task created successfully

Status: 201

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Fix the login button on the homepage",
  "creator": {
    "id": 1
  },
  "creator_type": "user",
  "owner": {
    "id": 1
  },
  "repository": {
    "id": 1296269
  },
  "state": "queued",
  "session_count": 1,
  "artifacts": [],
  "archived_at": null,
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

Get a task by repo

Note

This endpoint is in public preview and is subject to change.

Returns a task by ID scoped to an owner/repo path

Fine-grained access tokens for "Get a task by repo"

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)

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

“”Get a task by repo 的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`owner` string 必须 The account owner of the repository. The name is not case sensitive.
`repo` string 必须 The name of the repository. The name is not case sensitive.
`task_id` string 必须 The unique identifier of the task.

“Get a task by repo”的 HTTP 响应状态代码

状态代码	说明
`200`	Task retrieved successfully
`400`	Bad request
`401`	Authentication required
`403`	Insufficient permissions
`404`	Resource not found
`422`	Validation Failed

“Get a task by repo”的代码示例

请求示例

get/agents/repos/{owner}/{repo}/tasks/{task_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/repos/OWNER/REPO/tasks/TASK_ID

Task retrieved successfully

Status: 200

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Fix the login button on the homepage",
  "creator": {
    "id": 1
  },
  "creator_type": "user",
  "owner": {
    "id": 1
  },
  "repository": {
    "id": 1296269
  },
  "state": "completed",
  "session_count": 1,
  "artifacts": [
    {
      "provider": "github",
      "type": "pull",
      "data": {
        "id": 42
      }
    }
  ],
  "archived_at": null,
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T01:00:00Z",
  "sessions": [
    {
      "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Fix the login button on the homepage",
      "user": {
        "id": 1
      },
      "owner": {
        "id": 1
      },
      "repository": {
        "id": 1296269
      },
      "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "state": "completed",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T01:00:00Z",
      "completed_at": "2025-01-01T01:00:00Z",
      "prompt": "Fix the login button on the homepage",
      "head_ref": "copilot/fix-1",
      "base_ref": "main",
      "model": "claude-sonnet-4.6"
    }
  ]
}

List tasks

Note

This endpoint is in public preview and is subject to change.

Returns a list of tasks for the authenticated user

Fine-grained access tokens for "List tasks"

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)

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

“”List tasks 的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

查询参数
名称, 类型, 说明
`per_page` integer The number of results per page (max 100). 默认: `30`
`page` integer The page number of the results to fetch. 默认: `1`
`sort` string The field to sort results by. Can be `updated_at` or `created_at`. 默认: `updated_at` 可以是以下选项之一: `updated_at`, `created_at`
`direction` string The direction to sort results. Can be `asc` or `desc`. 默认: `desc` 可以是以下选项之一: `asc`, `desc`
`state` string 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`.
`is_archived` boolean Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`. 默认: `false`
`since` string Only show tasks updated at or after this time (ISO 8601 timestamp)

“List tasks”的 HTTP 响应状态代码

状态代码	说明
`200`	Tasks retrieved successfully
`400`	Bad request
`401`	Authentication required
`403`	Insufficient permissions
`422`	Validation Failed

“List tasks”的代码示例

请求示例

get/agents/tasks

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/tasks

Tasks retrieved successfully

Status: 200

{
  "tasks": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Fix the login button on the homepage",
      "creator": {
        "id": 1
      },
      "creator_type": "user",
      "owner": {
        "id": 1
      },
      "repository": {
        "id": 1296269
      },
      "state": "completed",
      "session_count": 1,
      "artifacts": [
        {
          "provider": "github",
          "type": "pull",
          "data": {
            "id": 42
          }
        }
      ],
      "archived_at": null,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T01:00:00Z"
    }
  ]
}

Get a task by ID

Note

This endpoint is in public preview and is subject to change.

Returns a task by ID with its associated sessions

Fine-grained access tokens for "Get a task by ID"

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)

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

“”Get a task by ID 的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`task_id` string 必须 The unique identifier of the task.

“Get a task by ID”的 HTTP 响应状态代码

状态代码	说明
`200`	Task retrieved successfully
`400`	Problems parsing request
`401`	Authentication required
`403`	Insufficient permissions
`404`	Resource not found
`422`	Validation Failed

“Get a task by ID”的代码示例

请求示例

get/agents/tasks/{task_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/tasks/TASK_ID

Task retrieved successfully

Status: 200

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Fix the login button on the homepage",
  "creator": {
    "id": 1
  },
  "creator_type": "user",
  "owner": {
    "id": 1
  },
  "repository": {
    "id": 1296269
  },
  "state": "completed",
  "session_count": 1,
  "artifacts": [
    {
      "provider": "github",
      "type": "pull",
      "data": {
        "id": 42
      }
    }
  ],
  "archived_at": null,
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T01:00:00Z",
  "sessions": [
    {
      "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Fix the login button on the homepage",
      "user": {
        "id": 1
      },
      "owner": {
        "id": 1
      },
      "repository": {
        "id": 1296269
      },
      "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "state": "completed",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T01:00:00Z",
      "completed_at": "2025-01-01T01:00:00Z",
      "prompt": "Fix the login button on the homepage",
      "head_ref": "copilot/fix-1",
      "base_ref": "main",
      "model": "claude-sonnet-4.6"
    }
  ]
}