Skip to main content
GET
/
v1
/
deep_research_tasks
/
{task_id}
Get Deep Research Task
curl --request GET \
  --url https://api.extruct.ai/v1/deep_research_tasks/{task_id} \
  --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 a Deep Research task’s status, progress, and — once the task is done — the report.

​
Example request

export EXTRUCT_API_TOKEN="YOUR_API_TOKEN"

curl "https://api.extruct.ai/v1/deep_research_tasks/<task_id>" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}"
Poll every 10–15 seconds until status is done or failed. Tasks typically take minutes; deeper tasks take longer.

​
Reading the response

  • status: created → in_progress → done or failed.
  • Progress counters while running: iterations (analysis steps), agents (research agents completed — this is what is billed), sources (unique sources collected).
  • report is null until done, then one of two shapes tagged by kind:
    • "kind": "markdown" — a markdown report whose bracketed citations like [1] resolve against the sources registry (id → URL).
    • "kind": "schema" — fields conforming to your output_schema, basis mapping every field to the source ids supporting it, and the sources registry. A done schema report always validates against your schema.
  • report.degradation_reasons: plain-language notes when something reduced coverage (research stopped at its budget or step limit, or some research agents failed). Empty for a clean run. Show these to your users alongside the report.
  • failure_reason (when status is failed): why the task failed — a rejected brief includes suggestions for fixing it. Failed tasks refund all their charges.

​
Common errors

​
401 Unauthorized

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

​
403 Forbidden

The task belongs to another user outside your organization.

​
404 Not Found

No task with this ID exists.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
task_id
string<uuid>
required

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.