Create Deep Research Task

POST

deep_research_tasks

curl --request POST \
  --url https://api.extruct.ai/v1/deep_research_tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "brief": "<string>",
  "depth": "medium",
  "output_schema": {}
}
'

{
  "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 creates a Deep Research task and returns a task ID immediately. Deep Research takes a free-text brief about one research target — a company, a person or team, an account, a market question — and produces a cited report: a reasoning agent plans the research, fans out research agents that gather evidence, and synthesizes the result. Use Deep Search instead when you want to discover many companies matching criteria; use Deep Research when you want a deep, sourced report.

Example request

export EXTRUCT_API_TOKEN="YOUR_API_TOKEN"

curl -X POST "https://api.extruct.ai/v1/deep_research_tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  -d '{
    "brief": "We sell a cloud cost-optimization platform to large enterprises; typical buyers are VPs of Infrastructure and FinOps leads. I am preparing outreach to Shell. Research how Shell'"'"'s IT and digital organization is structured, who owns cloud infrastructure and FinOps decisions, which cloud, data, or efficiency initiatives they announced in the last 18 months, and which vendors or system integrators they already work with. I want practical conversation angles tied to live initiatives, plus any signals of cost-cutting programs or budget pressure.",
    "depth": "medium"
  }'

Write the brief as a detailed paragraph, not a one-liner: include what you sell or research, who the target is, what decision the report should support, and time windows that matter. The more context and specifics the brief carries, the better the report. People are first-class targets — researching a lead and the team they work with is as valid as researching a company:

curl -X POST "https://api.extruct.ai/v1/deep_research_tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  -d '{
    "brief": "Here is my company: example.com. We sell AI-powered sales-enablement software to mid-market B2B teams. Research this person and the team they work with: https://www.linkedin.com/in/example-profile. I want their role and scope, what their team owns, recent initiatives or public statements, tools they already use, and the best angle to open a conversation.",
    "depth": "medium"
  }'

For a structured report, pass an output_schema:

curl -X POST "https://api.extruct.ai/v1/deep_research_tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  -d '{
    "brief": "We provide fraud-prevention APIs for fintech platforms and are building an account plan for Stripe. Summarize Stripe'"'"'s enterprise product initiatives from the last 12 months, identify concrete product or partnership angles where a fraud-prevention vendor could plug in, and flag risks that could stall a deal.",
    "depth": "high",
    "output_schema": {
      "type": "object",
      "properties": {
        "summary": {"type": "string"},
        "recommended_angles": {"type": "array", "items": {"type": "string"}},
        "risks": {"type": "array", "items": {"type": "string"}}
      },
      "required": ["summary", "recommended_angles", "risks"]
    }
  }'

Key parameters

brief (required): free-text research brief about a company, a person, or a team, up to 20,000 characters. Write it like a request to a research analyst — a detailed paragraph naming the target(s), your own context, and the decision the report should support. Detailed, specific briefs reliably produce better reports than one-liners.
depth (optional, default medium): the maximum research-agent budget — medium = 25, high = 50, xhigh = 75 agents. Starting a task requires the full budget in available credits; you are billed only for agents that actually run.
output_schema (optional): a JSON Schema object ("type": "object", with optional properties and required). When present, the report is structured and guaranteed to conform to this schema. Omit for a markdown report.

Endpoint behavior

The call validates the request and schedules the task, then returns immediately. No research runs at request time; poll with Get Task.
Creation is all-or-nothing: a success response means the system owns delivery; on a scheduling failure (503) nothing was created and it is safe to retry.
Billing is per completed research agent (1 credit each). A simple brief at xhigh that finishes after 8 agents costs 8 credits. Failed tasks refund all their charges.
Briefs that cannot produce useful research (no identifiable target, unusable input) are rejected asynchronously: the task ends failed with the reasons and fix-it suggestions in failure_reason, and nothing is charged.

Success signal

A successful response includes the task id with status: "created". Save id and poll Get Task until status is done or failed.

Common errors

`401 Unauthorized`

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

`402 Payment Required`

Two cases, distinguished by detail.error:

plan_required: Deep Research requires a Pro plan.
insufficient_credits: your available credits are below the full depth budget. The detail includes required_credits and available_credits — a lower depth may still fit.

`422 Unprocessable Entity`

Common causes:

Empty brief, or brief longer than 20,000 characters.
depth outside medium / high / xhigh (values are lowercase).
output_schema is not a valid JSON Schema object — the schema is validated in full at creation time, including nested property definitions.

Validate body first:

echo '<json-body>' | jq empty

`503 Service Unavailable`

Scheduling is temporarily unavailable. No task was created and nothing was charged — retry the call.

Deep Research

Authorizations

Authorization

string

header

required

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

Body

application/json

brief

string

required

Free-text research brief about a company, a person, or a team. Write it like a request to a research analyst — a detailed paragraph naming the target(s), your own context (what you sell or research, who the buyer is), the decision the report should support, and time windows that matter. Detailed, specific briefs reliably produce better reports than one-liners.

Required string length: 1 - 20000

depth

enum<string>

default:medium

Research depth: the maximum research-agent budget (medium=25, high=50, xhigh=75). Starting a task requires the full budget in available credits; only agents that actually run are billed.

Available options:

medium,

high,

xhigh

output_schema

Output Schema · object

Optional JSON Schema for structured report output; accepts an object schema (type: "object", with optional properties and required). Omit for markdown report output.

Response

Successful Response

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

Show child attributes

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.

DeepResearchMarkdownReport
DeepResearchSchemaReport

Show child attributes

Get Deep Research TaskGet a Deep Research task by ID.

Create Deep Research Task

curl --request POST \
  --url https://api.extruct.ai/v1/deep_research_tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "brief": "<string>",
  "depth": "medium",
  "output_schema": {}
}
'

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

​Example request

​Key parameters

​Endpoint behavior

​Success signal

​Common errors

​401 Unauthorized

​402 Payment Required

​422 Unprocessable Entity

​503 Service Unavailable

​Related endpoints

​Related guides

Authorizations

Body

Response

Overview

Example request

Key parameters

Endpoint behavior

Success signal

Common errors

`401 Unauthorized`

`402 Payment Required`

`422 Unprocessable Entity`

`503 Service Unavailable`

Related endpoints

Related guides