---
title: "Retrieve an async task"
method: GET
path: "/v1/async_tasks/{task_id}"
tags: ["Async tasks"]
---

# Retrieve an async task

`GET /v1/async_tasks/{task_id}`

## Path parameters

- `task_id` string, required — The ID of the async task to retrieve.

## Headers

- `Notion-Version` '2026-03-11', required

## Response `200`

- union
  - object
    - `object` 'async_task', required
    - `id` string, required
    - `status_url` string, required
    - `created_time` string, date-time, required
    - `operation` object, required
      - `surface` 'rest' | 'mcp', required
      - `name` string, required
    - `status` 'queued' | 'running' | 'retrying', required
    - `poll_after_seconds` integer, required
  - object
    - `object` 'async_task', required
    - `id` string, required
    - `status_url` string, required
    - `created_time` string, date-time, required
    - `operation` object, required
      - `surface` 'rest' | 'mcp', required
      - `name` string, required
    - `status` 'succeeded', required
    - `result` object, required
  - object
    - `object` 'async_task', required
    - `id` string, required
    - `status_url` string, required
    - `created_time` string, date-time, required
    - `operation` object, required
      - `surface` 'rest' | 'mcp', required
      - `name` string, required
    - `status` 'failed', required
    - `error` union, required
      - object
        - `object` 'error', required
        - `status` 400, required
        - `code` 'invalid_json', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 400, required
        - `code` 'invalid_request_url', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 400, required
        - `code` 'invalid_request', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 400, required
        - `code` 'missing_version', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 400, required
        - `code` 'invalid_beta', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 400, required
        - `code` 'validation_error', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 401, required
        - `code` 'unauthorized', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 403, required
        - `code` 'restricted_resource', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 404, required
        - `code` 'object_not_found', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 404, required
        - `code` 'directory_not_found', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 429, required
        - `code` 'rate_limited', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 529, required
        - `code` 'service_overload', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 500, required
        - `code` 'internal_server_error', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 503, required
        - `code` 'service_unavailable', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 504, required
        - `code` 'gateway_timeout', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 409, required
        - `code` 'conflict_error', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 409, required
        - `code` 'idempotency_key_reused', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 406, required
        - `code` 'row_limit_exceeded', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 403, required
        - `code` 'status_change_not_allowed', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 409, required
        - `code` 'agent_deleted', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 400, required
        - `code` 'invalid_credit_limit', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 403, required
        - `code` 'workspace_credits_exhausted', required
        - `message` string, required
        - `additional_data` object
      - object
        - `object` 'error', required
        - `status` 403, required
        - `code` 'agent_credit_limit_reached', required
        - `message` string, required
        - `additional_data` object

## Other responses

- `400`
- `401`
- `403`
- `404`
- `406`
- `409`
- `429`
- `500`
- `503`
- `504`
- `529`

## Changes

- **2026-08-15** `c90a4587bc95` — 1 breaking, 1 warning
  - added `subschema #17` to the `oneOf[subschema #3]/error` response property `oneOf` list for the response status `200`
  - added the new `idempotency_key_reused` enum value to the `allOf[subschema #2]/code` response property for the response status `409`
- **2026-08-13** `ae20477af71b` — 1 breaking, 1 info
  - added `subschema #1, subschema #2, subschema #3` to the response body `oneOf` list for the response status `403`
  - removed `#/components/schemas/publicApiCommonErrorResponse, subschema #2` from the response body `allOf` list for the response status `403`
- **2026-08-12** `28d140865fc6` — 1 breaking, 2 warning
  - added `subschema #21, subschema #22` to the `oneOf[subschema #3]/error` response property `oneOf` list for the response status `200`
  - added the new `agent_credit_limit_reached` enum value to the `allOf[subschema #2]/code` response property for the response status `403`
  - added the new `workspace_credits_exhausted` enum value to the `allOf[subschema #2]/code` response property for the response status `403`
- …earlier changes not shown

[Full history](https://skmtc.dev/notion/apis/notion-api/changes/v1/async_tasks/:task_id/get.md)

---

[API](https://skmtc.dev/notion/apis/notion-api.md) · [All operations](https://skmtc.dev/notion/apis/notion-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/notion/notion-api/revisions/d125dfa2cde5/schema)