Retrieve an async task

Retrieve the status and result of an async task.

GET /v1/async_tasks/{task_id}

TypeScript SDK

JavaScript

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

curl --request GET \
  --url https://api.notion.com/v1/async_tasks/{task_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Notion-Version: <notion-version>'

import requests

url = "https://api.notion.com/v1/async_tasks/{task_id}"

headers = {
    "Notion-Version": "<notion-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notion.com/v1/async_tasks/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Notion-Version: <notion-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/async_tasks/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Notion-Version", "<notion-version>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.notion.com/v1/async_tasks/{task_id}")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/async_tasks/{task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

200

{
  "object": "<string>",
  "id": "<string>",
  "status_url": "<string>",
  "created_time": "2023-11-07T05:31:56Z",
  "operation": {
    "name": "<string>"
  },
  "poll_after_seconds": 1
}

{
  "object": "<unknown>",
  "message": "<string>",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "unauthorized",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "restricted_resource",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "row_limit_exceeded",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "conflict_error",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "rate_limited",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "internal_server_error",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "service_unavailable",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "gateway_timeout",
  "status": "<unknown>",
  "additional_data": {}
}

{
  "object": "<unknown>",
  "message": "<string>",
  "code": "service_overload",
  "status": "<unknown>",
  "additional_data": {}
}

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:

{
  "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:

{
  "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

200

application/json

Option 1

Option 2

Option 3

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

Show child attributes

status · enum<string> · required

Available options: queued, running, retrying

poll_after_seconds · integer · required

Required range: x >= 0