> ## Documentation Index > Fetch the complete documentation index at: https://developers.notion.com/llms.txt > Use this file to discover all available pages before exploring further. > Retrieve the status and result of an async task. # Retrieve an async task Use this endpoint to poll an `async_task` returned by an operation that was accepted for background execution. The first async-capable REST endpoints are: | Operation | Async support | | ----------------------------------- | ----------------------------------------------------------------------- | | `POST /v1/pages` | Supported only when the request includes the `markdown` body parameter. | | `PATCH /v1/pages/:page_id/markdown` | Supported for markdown update requests. | Set `allow_async: true` on a supported operation to opt into an `async_task` response. When `allow_async` is omitted or `false`, the endpoint keeps its existing synchronous response shape. `allow_async` changes response behavior only; it does not change validation, permissions, or the operation being performed. Async task completion is polling-first in this version. Webhook notifications and ETA estimates are not part of the async task contract. ### Async task response When an operation is accepted for background execution, the supported endpoint returns HTTP `202` with an `async_task` object: ```json theme={null} { "object": "async_task", "id": "task_abc123", "status": "queued", "status_url": "https://api.notion.com/v1/async_tasks/task_abc123", "created_time": "2026-06-29T12:00:00.000Z", "poll_after_seconds": 2, "operation": { "surface": "rest", "name": "PATCH /v1/pages/:page_id/markdown" } } ``` Use `status_url`, or call this endpoint with the returned `id`, to check completion. ### Status values | Status | Meaning | | ----------- | -------------------------------------------------------------------------------------------------------------- | | `queued` | The task has been accepted and persisted, but processing has not started. | | `running` | A worker is processing the task. | | `retrying` | The task hit a retryable infrastructure or downstream-service failure and is scheduled to retry. | | `succeeded` | The task completed successfully. The response includes a `result` object. | | `failed` | The task failed terminally. The response includes an `error` object using the standard Public API error shape. | For non-terminal statuses (`queued`, `running`, and `retrying`), wait at least `poll_after_seconds` before polling again. Completed and failed task metadata is retained for a bounded period. After expiry, polling the task returns the standard not-found response, so store any final result data your application needs. ### Polling responses An in-progress task includes the latest non-terminal status and polling guidance: ```json theme={null} { "object": "async_task", "id": "task_abc123", "status": "running", "status_url": "https://api.notion.com/v1/async_tasks/task_abc123", "created_time": "2026-06-29T12:00:00.000Z", "poll_after_seconds": 2, "operation": { "surface": "rest", "name": "PATCH /v1/pages/:page_id/markdown" } } ``` A successful task includes the operation result: ```json theme={null} { "object": "async_task", "id": "task_abc123", "status": "succeeded", "status_url": "https://api.notion.com/v1/async_tasks/task_abc123", "created_time": "2026-06-29T12:00:00.000Z", "operation": { "surface": "rest", "name": "PATCH /v1/pages/:page_id/markdown" }, "result": { "object": "page_markdown", "id": "page-uuid", "markdown": "# Updated page\n\nThe update is complete.", "truncated": false, "unknown_block_ids": [] } } ``` A failed task includes a standard Public API error object: ```json theme={null} { "object": "async_task", "id": "task_abc123", "status": "failed", "status_url": "https://api.notion.com/v1/async_tasks/task_abc123", "created_time": "2026-06-29T12:00:00.000Z", "operation": { "surface": "rest", "name": "PATCH /v1/pages/:page_id/markdown" }, "error": { "object": "error", "status": 400, "code": "validation_error", "message": "The request body was invalid." } } ``` ### Errors Returns a 404 HTTP response if the async task does not exist, has expired, or is not visible to the current connection. Returns a 429 HTTP response if polling exceeds [request limits](/reference/request-limits). Malformed requests can return a 400 HTTP response. *Each Public API endpoint can return several possible error codes. See the [Error codes section](/reference/status-codes#error-codes) of the Status codes documentation for more information.* ## OpenAPI ````yaml openapi.json GET /v1/async_tasks/{task_id} openapi: 3.1.0 info: title: Notion API version: 1.0.0 termsOfService: >- https://notion.notion.site/Terms-and-Privacy-28ffdd083dc3473e9c2da6ec011b58ac servers: - url: https://api.notion.com security: - bearerAuth: [] tags: - name: Databases description: Database endpoints - name: Data sources description: Data source endpoints - name: Pages description: Page endpoints - name: Async tasks description: Async task endpoints - name: Blocks description: Block endpoints - name: Comments description: Comment endpoints - name: File uploads description: File upload endpoints - name: OAuth description: OAuth endpoints (basic authentication) - name: Users description: User endpoints - name: Search description: Search endpoints - name: Views description: View endpoints - name: Custom emojis description: Custom emoji endpoints - name: Meeting notes description: Meeting notes endpoints paths: /v1/async_tasks/{task_id}: get: tags: - Async tasks summary: Retrieve an async task operationId: retrieve-async-task parameters: - name: task_id in: path required: true schema: type: string minLength: 1 examples: - task_abc123 description: The ID of the async task to retrieve. - $ref: '#/components/parameters/notionVersion' responses: '200': description: '' content: application/json: schema: oneOf: - type: object required: - object - id - status - status_url - created_time - operation - poll_after_seconds additionalProperties: false properties: object: type: string const: async_task id: type: string minLength: 1 status_url: type: string minLength: 1 created_time: type: string format: date-time operation: type: object required: - surface - name additionalProperties: false properties: surface: type: string enum: - rest - mcp name: type: string minLength: 1 status: type: string enum: - queued - running - retrying poll_after_seconds: type: integer minimum: 0 - type: object required: - object - id - status - status_url - created_time - operation - result additionalProperties: false properties: object: type: string const: async_task id: type: string minLength: 1 status_url: type: string minLength: 1 created_time: type: string format: date-time operation: type: object required: - surface - name additionalProperties: false properties: surface: type: string enum: - rest - mcp name: type: string minLength: 1 status: type: string const: succeeded result: type: object additionalProperties: $ref: >- #/components/schemas/publicApiAsyncTaskStatusResultJsonValue - type: object required: - object - id - status - status_url - created_time - operation - error additionalProperties: false properties: object: type: string const: async_task id: type: string minLength: 1 status_url: type: string minLength: 1 created_time: type: string format: date-time operation: type: object required: - surface - name additionalProperties: false properties: surface: type: string enum: - rest - mcp name: type: string minLength: 1 status: type: string const: failed error: oneOf: - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 400 code: type: string const: invalid_json message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 400 code: type: string const: invalid_request_url message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 400 code: type: string const: invalid_request message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 400 code: type: string const: missing_version message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 400 code: type: string const: validation_error message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 401 code: type: string const: unauthorized message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 403 code: type: string const: restricted_resource message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 404 code: type: string const: object_not_found message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 429 code: type: string const: rate_limited message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 529 code: type: string const: service_overload message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 500 code: type: string const: internal_server_error message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 503 code: type: string const: service_unavailable message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 504 code: type: string const: gateway_timeout message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 409 code: type: string const: conflict_error message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string - type: object required: - object - status - code - message additionalProperties: false properties: object: type: string const: error status: type: integer const: 409 code: type: string const: row_limit_exceeded message: type: string minLength: 1 additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string '400': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_400' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_401' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_403' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_404' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_409' '429': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_429' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_500' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_503' '504': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_504' '529': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_529' x-codeSamples: - lang: javascript label: TypeScript SDK source: |- import { Client } from "@notionhq/client" const notion = new Client({ auth: process.env.NOTION_API_KEY }) const response = await notion.asyncTasks.retrieve({ task_id: "task_abc123" }) components: parameters: notionVersion: name: Notion-Version in: header required: true schema: enum: - '2026-03-11' description: >- The [API version](/reference/versioning) to use for this request. The latest version is `2026-03-11`. schemas: publicApiAsyncTaskStatusResultJsonValue: oneOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: $ref: '#/components/schemas/publicApiAsyncTaskStatusResultJsonValue' - type: object additionalProperties: $ref: '#/components/schemas/publicApiAsyncTaskStatusResultJsonValue' error_api_400: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - invalid_json - invalid_request_url - invalid_request - missing_version - validation_error status: const: 400 required: - code - status additionalProperties: false error_api_401: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - unauthorized status: const: 401 required: - code - status additionalProperties: false error_api_403: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - restricted_resource status: const: 403 required: - code - status additionalProperties: false error_api_404: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - object_not_found status: const: 404 required: - code - status additionalProperties: false error_api_409: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - conflict_error - row_limit_exceeded status: const: 409 required: - code - status additionalProperties: false error_api_429: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - rate_limited status: const: 429 required: - code - status additionalProperties: false error_api_500: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - internal_server_error status: const: 500 required: - code - status additionalProperties: false error_api_503: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - service_unavailable status: const: 503 required: - code - status additionalProperties: false error_api_504: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - gateway_timeout status: const: 504 required: - code - status additionalProperties: false error_api_529: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - service_overload status: const: 529 required: - code - status additionalProperties: false publicApiCommonErrorResponse: type: object properties: object: const: error message: type: string additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string required: - object - message securitySchemes: bearerAuth: type: http scheme: bearer ````