---
title: "Start a research task"
method: POST
path: "/tasks/v1/research"
tags: ["Web Tasks"]
---

# Start a research task

`POST /tasks/v1/research`

## Request

- Base URL: `https://api.oassis.dev`
- URL: `https://api.oassis.dev/tasks/v1/research`
- Auth: one of:
  - HTTP bearer
  - none

Answers a question by reading public pages, with sources, progress and cost. With an API key, HTTP reserves credits and settles actual cost. Without a key, x402 pays a fixed execution budget in limits.max_cost_usd. MCP start requires an API key and reserves credits, settling actual cost. With an API key, use the owning key for free status/cancel and send Idempotency-Key (required, maximum 100 characters). The x402 response returns access_token: send it as Task-Token for status/cancel. For x402 retries send the same Task-Token and Idempotency-Key (maximum 200 characters). A 202 confirms acceptance, not a completed result.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `task` string, required: What to find out, in plain words. Be specific about what to compare.
  - `mode` 'research': Only research is available: read public pages and answer.
  - `urls` string[]: Pages to read first, up to 5. Public http or https urls only.
  - `limits` object: Bounds on cost, time and steps.
    - `max_cost_usd` number: Most the task may cost, in USD. Execution budget. Reserved against account credits over MCP/HTTP with an API key; charged as a fixed package over HTTP/x402. No automatic on-chain refund.
    - `max_duration_seconds` integer: Longest the task may run, in seconds.
    - `max_steps` integer: Most decisions the planner may take.

## Response `202`

Accepted, not completed. Location points at the task. Body includes task_id, status and location; x402 also returns access_token. Poll status until a terminal outcome.

## Other responses

- `400`: The request does not match the contract. Unknown fields and unsupported modes are refused.
- `401`: Missing or invalid owner API key or task-scoped access token.
- `402`: Insufficient account credits, or x402 payment required without an API key.
- `409`: The Idempotency-Key was used with a different request.

---

[API](https://skmtc.dev/oassis/apis/oassis-web-scraping-crawling-and-browser-control-for-ai-agen.md) · [All operations](https://skmtc.dev/oassis/apis/oassis-web-scraping-crawling-and-browser-control-for-ai-agen/llms.txt) · [OpenAPI document](https://skmtc.dev/oassis/apis/oassis-web-scraping-crawling-and-browser-control-for-ai-agen/revisions/dedc2b717b91?raw)