Skip to main content
GET
/
v1
/
deep_research_tasks
List Deep Research Tasks
curl --request GET \
  --url https://api.extruct.ai/v1/deep_research_tasks \
  --header 'Authorization: Bearer <token>'
[
  {
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "brief": "<string>",
    "iterations": 123,
    "agents": 123,
    "sources": 123,
    "owner": {
      "id": "<string>",
      "email": "<string>"
    },
    "output_schema": {},
    "failure_reason": "<string>",
    "report": {
      "markdown": "<string>",
      "sources": [
        {
          "id": 123,
          "url": "<string>"
        }
      ],
      "kind": "markdown",
      "degradation_reasons": []
    }
  }
]

Overview

This endpoint returns your Deep Research tasks, newest first, with their current statuses and progress counters.

Example request

export EXTRUCT_API_TOKEN="YOUR_API_TOKEN"

curl --get "https://api.extruct.ai/v1/deep_research_tasks" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=20"

Key parameters

  • offset (optional): pagination offset.
  • limit (optional): page size; defaults to 50.

Success signal

A successful response returns an array of tasks with id, status, brief, depth, progress counters, and the report for finished tasks.

Common errors

401 Unauthorized

Check that your header is Authorization: Bearer ${EXTRUCT_API_TOKEN}.

Authorizations

Authorization
string
header
required

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

Query Parameters

offset
integer | null
limit
integer | null

Page size; defaults to 50.

Response

Successful Response

id
string
required
created_at
string<date-time>
required
updated_at
string<date-time>
required
status
enum<string>
required

Task lifecycle: created -> in_progress -> done or failed.

Available options:
created,
in_progress,
done,
failed
brief
string
required
depth
enum<string>
required
Available options:
medium,
high,
xhigh
iterations
integer
required

Research analysis steps completed so far.

agents
integer
required

Research agents completed so far; billing is one credit per agent.

sources
integer
required

Unique sources collected across all research agents.

owner
OwnerInfo · object
required
output_schema
Output Schema · object
failure_reason
string | null

Why the task failed, when status is failed: a rejected brief (with suggestions for fixing it), insufficient credits mid-run, or an internal error. Failed tasks refund their charges.

report
DeepResearchMarkdownReport · object

Markdown report payload, returned when no output_schema was provided.