Agent tasks - GitHub Enterprise Cloud Docs

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

Parameters for "List tasks for repository"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository. The name is not case sensitive.

Query parameters
Name, Type, Description
`per_page` integer The number of results per page (max 100). Default: `30`
`page` integer The page number of the results to fetch. Default: `1`
`sort` string The field to sort results by. Can be `updated_at` or `created_at`. Default: `updated_at` Can be one of: `updated_at`, `created_at`
`direction` string The direction to sort results. Can be `asc` or `desc`. Default: `desc` Can be one of: `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`. Default: `false`
`since` string Only show tasks updated at or after this time (ISO 8601 timestamp)
`creator_id` integer Filter tasks by creator user ID

HTTP response status codes for "List tasks for repository"

Status code	Description
`200`	Tasks retrieved successfully
`400`	Bad request
`401`	Authentication required
`403`	Insufficient permissions
`404`	Resource not found
`422`	Validation Failed

Code samples for "List tasks for repository"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

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"
    }
  ]
}

Create a task

Note

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

Creates a new task for a repository.

Parameters for "Create a task"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository. The name is not case sensitive.

Body parameters
Name, Type, Description
`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`
`create_pull_request` boolean Whether to create a PR. Default: `false`
`base_ref` string Base ref for new branch/PR

HTTP response status codes for "Create a task"

Status code	Description
`201`	Task created successfully
`400`	Problems parsing JSON
`401`	Authentication required
`403`	Insufficient permissions
`422`	Validation Failed

Code samples for "Create a task"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

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

Parameters for "Get a task by repo"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository. The name is not case sensitive.
`task_id` string Required The unique identifier of the task.

HTTP response status codes for "Get a task by repo"

Status code	Description
`200`	Task retrieved successfully
`400`	Bad request
`401`	Authentication required
`403`	Insufficient permissions
`404`	Resource not found
`422`	Validation Failed

Code samples for "Get a task by repo"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

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

Parameters for "List tasks"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Query parameters
Name, Type, Description
`per_page` integer The number of results per page (max 100). Default: `30`
`page` integer The page number of the results to fetch. Default: `1`
`sort` string The field to sort results by. Can be `updated_at` or `created_at`. Default: `updated_at` Can be one of: `updated_at`, `created_at`
`direction` string The direction to sort results. Can be `asc` or `desc`. Default: `desc` Can be one of: `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`. Default: `false`
`since` string Only show tasks updated at or after this time (ISO 8601 timestamp)

HTTP response status codes for "List tasks"

Status code	Description
`200`	Tasks retrieved successfully
`400`	Bad request
`401`	Authentication required
`403`	Insufficient permissions
`422`	Validation Failed

Code samples for "List tasks"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

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

Parameters for "Get a task by ID"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`task_id` string Required The unique identifier of the task.

HTTP response status codes for "Get a task by ID"

Status code	Description
`200`	Task retrieved successfully
`400`	Problems parsing request
`401`	Authentication required
`403`	Insufficient permissions
`404`	Resource not found
`422`	Validation Failed

Code samples for "Get a task by ID"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

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"
    }
  ]
}