Skip to main content
GET
List Deep Research Tasks

Overview

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

Example request

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 two credits per agent.

sources
integer
required

Unique sources collected across all research agents.

owner
OwnerInfo · object
required
output_schema
Output Schema · object | null
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.