Skip to main content
GET
/
v1
/
async_tasks
/
{task_id}
TypeScript SDK
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"
})
{
  "object": "<string>",
  "id": "<string>",
  "status_url": "<string>",
  "created_time": "2023-11-07T05:31:56Z",
  "operation": {
    "name": "<string>"
  },
  "poll_after_seconds": 1
}
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:
OperationAsync support
POST /v1/pagesSupported only when the request includes the markdown body parameter.
PATCH /v1/pages/:page_id/markdownSupported 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: 
{
  "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

StatusMeaning
queuedThe task has been accepted and persisted, but processing has not started.
runningA worker is processing the task.
retryingThe task hit a retryable infrastructure or downstream-service failure and is scheduled to retry.
succeededThe task completed successfully. The response includes a result object.
failedThe 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: 
{
  "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: 
{
  "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: 
{
  "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. Malformed requests can return a 400 HTTP response. Each Public API endpoint can return several possible error codes. See the Error codes section of the Status codes documentation for more information.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Notion-Version
enum<string>
required

The API version to use for this request. The latest version is 2026-03-11.

Available options:
2026-03-11

Path Parameters

​
task_id
string
required

The ID of the async task to retrieve.

Minimum string length: 1
Example:

"task_abc123"

Response

​
object
string
required
Allowed value: "async_task"
​
id
string
required
Minimum string length: 1
​
status_url
string
required
Minimum string length: 1
​
created_time
string<date-time>
required
​
operation
object
required
​
status
enum<string>
required
Available options:
queued,
running,
retrying
​
poll_after_seconds
integer
required
Required range: x >= 0