Quickstart

Run your first search.

1. Get a key

Sign up at console.hyperresearch.ai, then create a scoped key under API keys. No sales call is needed. Keys are bearer keys and are shown once: store the key in an environment variable, grant only the scopes the integration needs, and never put it in a browser URL. See Authentication.

• Keys that start hr_test_ run in fixture mode: free and never billed. The writing steps are replaced by deterministic placeholders, so the report is not real research, but the run lifecycle and response shapes are the real ones. Build and test the integration with one first.
• Keys that start hr_live_ run real, billed research.

2. Pick a run size

Two sizes are on sale, priced flat per run and charged on one monthly invoice. There is no subscription.

Size	tier	Price	Typical run
Light	light	$9	About 30 to 40 minutes, about 20 to 50 sources
Deep	premier	$49	About 3 to 5 hours, about 150 to 200 sources, with a verification receipt

Wall times and source counts are targets, not guarantees. Start with Light unless the question has several distinct parts. Adding a card makes an account’s first Deep run free, once per account. A new account’s monthly spend cap is $500; change it in the console or with PATCH /v1/billing/spend-cap (Billing).

3. Submit a run

The API returns the price before work enters the queue. Keep the idempotency key stable if you retry the same request; use a new one for each new question.

curl https://api.hyperresearch.ai/v1/runs \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: research-2026-09-14-01" \
  -d '{"query":"What changed in grid-scale storage policy?","tier":"light"}'

The response carries the run id at once.

4. Follow it and fetch the report

• Poll GET /v1/runs/{id} every minute or so. Statuses: clarifying, queued, running, paused, blocked, done, failed, aborted.
• Or stream GET /v1/runs/{id}/events, or register a webhook.
• If the status is clarifying, answer with POST /v1/runs/{id}/clarify.
• When it is done, fetch GET /v1/runs/{id}/result.

Every source the run read stays in the workspace vault. Errors are JSON with a stable code; Errors says which are safe to retry. Every endpoint is in the API reference and the OpenAPI document.

Connect an agent over MCP

Point any MCP client at the hosted server (streamable HTTP):

https://mcp.hyperresearch.ai/mcp

The client discovers the authorization server and opens a browser sign-in (OAuth with PKCE); no key is needed. A client that asks for no scopes gets mcp vault:read runs:read; starting runs or other metered work needs runs:write, vault:write, fetch or verify. Tools include start_run, run_status, answer_clarification, run_result, search_notes, read_note and verify_citations. A run takes minutes to hours, so an agent starts it and polls rather than waiting inside one tool call (Long-running runs over MCP). Setup per client: MCP server, Claude, Cursor, ChatGPT.

Answers: one question, one checked answer

For a single fact rather than a report, connect the Answers MCP server:

claude mcp add --transport http hyperresearch-answers https://answers.hyperresearch.ai/mcp

It has two tools. ask takes one question and returns a short answer with the quotes it rests on, each checked against its page, or not_found when no readable source states it. search returns ranked sources with word-for-word passages. Both are billed per call (ask from 5¢, search from 5¢), every account gets $5 of free credit with no card needed, and on the first tool call the client signs in through the browser. On a machine with no browser, send an API key as Authorization: Bearer <YOUR_API_KEY> instead. Modes, prices and setup for each client are on Answers MCP.