> ## Documentation Index > Fetch the complete documentation index at: https://docs.extruct.ai/llms.txt > Use this file to discover all available pages before exploring further. > Create a Deep Research task. # Create Deep Research Task ## 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](/api-reference/discover/create-company-discovery-task) instead when you want to *discover many companies* matching criteria; use Deep Research when you want a *deep, sourced report*. ## Example request ```bash theme={null} 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: ```bash theme={null} 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`: ```bash theme={null} 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` = 5, `high` = 15, `xhigh` = 25 agents. Each research agent that runs costs 2 credits. Starting a task reserves the full budget in available credits (`medium` = 10, `high` = 30, `xhigh` = 50); you are billed only for agents that actually run. * `output_schema` (optional): a JSON Schema object (`"type": "object"`). When present, the report is structured and guaranteed to conform to it; omit for markdown. Up to 5 levels of nesting and 50 properties, with root `#/$defs/` for shared definitions. To get sources and reasoning for a value, wrap it as an Evidenced object — `value`, `sources` (URLs), and `reasoning` — and the provenance comes back beside the value. See the [Deep Research guide](/api-guides/research/deep-research#sources-and-reasoning-inline). ## Endpoint behavior * The call validates the request and schedules the task, then returns immediately. No research runs at request time; poll with [Get Task](/api-reference/deep-research/get-deep-research-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 (2 credits each). A simple brief at `xhigh` that finishes after 8 agents costs 16 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](/api-reference/deep-research/get-deep-research-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: ```bash theme={null} echo '' | jq empty ``` ### `503 Service Unavailable` Scheduling is temporarily unavailable. No task was created and nothing was charged — retry the call. ## Related endpoints * [Get Task Endpoint](/api-reference/deep-research/get-deep-research-task) * [List Tasks Endpoint](/api-reference/deep-research/list-deep-research-tasks) ## Related guides * [Deep Research](/api-guides/research/deep-research) ## OpenAPI ````yaml post /v1/deep_research_tasks openapi: 3.1.0 info: title: FastAPI version: 0.1.0 servers: [] security: [] paths: /v1/deep_research_tasks: post: tags: - deep-research summary: Create Deep Research Task description: >- Create an asynchronous Deep Research task about a company, a person, or a team. Requires a Pro plan and the full depth budget in available credits. operationId: create_deep_research_task_v1_deep_research_tasks_post requestBody: content: application/json: schema: $ref: '#/components/schemas/DeepResearchTaskInput' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DeepResearchTaskOutput' '402': description: >- Payment Required. Detail includes error (insufficient_credits or plan_required), action, and for credit shortfalls required_credits and available_credits. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '503': description: Scheduling unavailable. No task was created; safe to retry. security: - HTTPBearer: [] components: schemas: DeepResearchTaskInput: properties: brief: type: string maxLength: 20000 minLength: 1 title: Brief description: >- 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. depth: type: string enum: - medium - high - xhigh title: Depth description: >- Research depth: the maximum research-agent budget (medium=5, high=15, xhigh=25). Each research agent that runs costs 2 credits. Starting a task reserves the full budget in available credits (medium=10, high=30, xhigh=50); only agents that actually run are billed. default: medium output_schema: anyOf: - type: object - type: 'null' title: Output Schema description: >- Optional JSON Schema for structured report output; an object schema (type: "object"), omit for markdown. Up to 5 levels of nesting and 50 properties, with root #/$defs/ for shared definitions. To get sources and reasoning for a value, wrap it as an Evidenced object (value + sources URLs + reasoning); the provenance comes back beside the value. type: object required: - brief title: DeepResearchTaskInput DeepResearchTaskOutput: properties: id: type: string title: Id created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At status: type: string enum: - created - in_progress - done - failed title: Status description: 'Task lifecycle: created -> in_progress -> done or failed.' brief: type: string title: Brief depth: type: string enum: - medium - high - xhigh title: Depth output_schema: anyOf: - type: object - type: 'null' title: Output Schema failure_reason: anyOf: - type: string - type: 'null' title: Failure Reason description: >- 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. iterations: type: integer title: Iterations description: Research analysis steps completed so far. agents: type: integer title: Agents description: Research agents completed so far; billing is two credits per agent. sources: type: integer title: Sources description: Unique sources collected across all research agents. report: anyOf: - oneOf: - $ref: '#/components/schemas/DeepResearchMarkdownReport' - $ref: '#/components/schemas/DeepResearchSchemaReport' discriminator: propertyName: kind mapping: markdown: $ref: '#/components/schemas/DeepResearchMarkdownReport' schema: $ref: '#/components/schemas/DeepResearchSchemaReport' - type: 'null' title: Report description: >- Null until status is done; then a markdown report or, when output_schema was provided, a structured schema report. owner: $ref: '#/components/schemas/OwnerInfo' type: object required: - id - created_at - updated_at - status - brief - depth - iterations - agents - sources - owner title: DeepResearchTaskOutput HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError DeepResearchMarkdownReport: properties: kind: type: string enum: - markdown title: Kind default: markdown markdown: type: string title: Markdown description: >- Markdown report. Bracketed numbers like [1] cite entries in `sources` by id. sources: items: $ref: '#/components/schemas/DeepResearchSource' type: array title: Sources description: Source registry (id -> url) that report citations resolve against. degradation_reasons: items: type: string type: array title: Degradation Reasons description: >- Plain-language notes when the report was produced under degraded conditions (early finalization, failed research agents). Empty for a clean run. Show these to the user alongside the report. default: [] type: object required: - markdown - sources title: DeepResearchMarkdownReport description: Markdown report payload, returned when no output_schema was provided. DeepResearchSchemaReport: properties: kind: type: string enum: - schema title: Kind default: schema fields: type: object title: Fields description: >- Structured report values conforming to the task output_schema. Provenance, where the schema opts in, is co-located inside `fields` as Evidenced wrappers (an object with `value`, a `sources` array of URLs, and a `reasoning` string). degradation_reasons: items: type: string type: array title: Degradation Reasons description: >- Plain-language notes when the report was produced under degraded conditions (early finalization, failed research agents). Empty for a clean run. Show these to the user alongside the report. default: [] type: object required: - fields title: DeepResearchSchemaReport description: Structured report payload, returned when output_schema was provided. OwnerInfo: properties: id: type: string title: Id email: type: string title: Email type: object required: - id - email title: OwnerInfo ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError DeepResearchSource: properties: id: type: integer title: Id url: type: string title: Url type: object required: - id - url title: DeepResearchSource description: A source available to the report by numeric id. securitySchemes: HTTPBearer: type: http scheme: bearer ````