Research belongs
in your workflow.

API keys and authentication

In the app, open Developers, then API keys, and click Create API key. The secret starts with fsr_live_ and is shown once (keys created before November 2026 start with sk_ and keep working). If you lose it, rotate the key to get a new secret; the old one stops working.

Send the key as Authorization: Bearer fsr_live_... or as X-API-Key: fsr_live_... on REST calls. The MCP endpoint accepts the Bearer header only.

New keys get read and run. A key can also carry an expiry (1 to 3,650 days) and a monthly credit cap; once a key reaches its cap, paid work through that key stops while reads keep working. Each plan limits how many active keys a workspace can hold (one on the free trial). Every operation in the API reference lists the scope it needs.

Runs, depth and retries

Credit prices come from the live price list on the pricing page. Source and time ranges are estimates. Deep research is not part of the free trial; starting one there answers 403 feature_not_available.

• questionRequired. Up to 2,000 characters. Specific questions tied to a decision get the most useful reports.
• depthstandard (default) or deep.
• research_typegeneral (default), competitive_intel, market_research, market_sizing, technical, content_strategy, social_strategy, academic, investigative or strategic.
• decision_context, intended_audienceOptional. What the research should help decide, and who will read it.
• preferred_domains, exclude_domains, time_rangeOptional. Steer the search: up to 30 preferred and 50 excluded domains, and day, week, month or year.
• namespace_id, tags, metadataOptional. Organize runs; metadata is your own JSON, up to 4 KB, returned unchanged.

Status

A run moves through pending or queued, then running, and ends as completed, failed or cancelled. A run started with "skip_clarifying": false waits in clarifying until you answer POST /v1/runs/RUN_ID/clarify. Cancel with POST /v1/runs/RUN_ID/cancel; the run stops before its next research round.

Idempotency

POST /v1/runs requires an Idempotency-Key header (any string up to 255 characters; a UUID works well). Repeat a request with the same key and the same body after a timeout and you get the original response back, with no second run and no second charge. The same key with a different body answers 409 idempotency_conflict. While the first request is still being admitted, a retry answers 409 idempotency_in_flight with Retry-After: 2. Use a new key for new work.

Streaming events

GET /v1/runs/RUN_ID/events is a server-sent event stream. Each frame has an id, an event type such as run.started, round.completed or run.completed, and a JSON data line. Comment lines (: heartbeat) keep the connection open.

• ResumeReconnect with Last-Event-ID set to the last id you saw and the stream continues after it.
• ResetA stream.reset frame means the stream skipped ahead. Read the run with GET /v1/runs/RUN_ID and carry on.
• Close it yourselfThe stream stays open after the run ends. Stop reading after run.completed, run.failed or run.cancelled.

Follow the investigation further

A finished run is a starting point. Ask its evidence a question, extend it with more rounds, follow a rabbit hole into one thread, or build a multi-document dossier. Each paid action takes its own Idempotency-Key (a new one per action), and its price is on the pricing page.

# One key per question; reuse it only to retry this same question.
export ASK_KEY=$(python3 -c 'import uuid; print(uuid.uuid4())')
curl -X POST https://api.farsideresearch.com/v1/runs/RUN_ID/ask \
  -H "Authorization: Bearer $FARSIDE_API_KEY" \
  -H "Idempotency-Key: $ASK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Which licensing change affects self-hosted users most?","allow_search":false}'

The answer comes back with numbered citations to the run's sources, plus credits_charged and free_question. Questions use your plan's free questions for the day first; "allow_search": true also searches the web for newer pages and is always charged. Asking a run that has not completed answers 409 run_not_completed.

Read the evidence trail

A report keeps its recommendation beside the available citations, source quality, conflicting evidence, and unresolved gaps. Review the source record before you carry the conclusion into the next decision.

• Claim-to-source linksFollow the support behind a recommendation.
• Conflicting evidenceSee the counter-signal instead of losing it in synthesis.
• Open gapsKeep unanswered questions visible for the next brief.

Reopen or export the report

Reading a report does not spend credits. Reopen the retained result when the decision needs review, or export it. GET /v1/runs/RUN_ID/export/FORMAT takes markdown, pdf, json or sources.csv (plus dossier.md, dossier.pdf and dossier.zip once a dossier is finished). It answers with a download_url that lasts 15 minutes, or with a status_url to poll while the file is built. Exports are free; your plan has to include the format.

Webhooks

Instead of polling, register an HTTPS endpoint in Developers, then Webhooks (or POST /v1/webhooks with an admin key) and pick the events you want, such as run.completed and run.failed. The signing secret starts with whsec_ and is shown once. Webhooks are part of paid plans.

{
  "id": "evt_6f1c0a9e2b7d4c1f8e3a5b9d0c2e4f61",
  "type": "run.completed",
  "created_at": "2026-10-29T14:03:11Z",
  "api_version": "v1",
  "data": {
    "run": {
      "id": "RUN_ID",
      "quality_score": 82
    }
  }
}

Each delivery carries X-Fathom-Event, X-Fathom-Delivery-Id and X-Signature: t=TIMESTAMP,v1=HEX, where HEX is the HMAC-SHA256 of TIMESTAMP. followed by the raw request body, keyed with your secret. Check it before you trust the payload, and reject old timestamps.

import hashlib, hmac, time

def verify(secret: str, signature_header: str, body: bytes, max_age: int = 300) -> bool:
    parts = dict(item.split("=", 1) for item in signature_header.split(","))
    timestamp, received = parts["t"], parts["v1"]
    if abs(time.time() - int(timestamp)) > max_age:
        return False
    expected = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)

Answer with any 2xx to acknowledge. Anything else is retried, up to 8 attempts with delays growing from one minute to a day. Treat the delivery id as the key for ignoring repeats.

Credits

Every paid action has a published credit price. Credits are reserved when the action starts, then settled when it finishes; a run that fails gives back what it reserved. When the balance can't cover a new run the API answers 402 insufficient_credits, and error.detail names required, available and shortfall. Reading runs, sources and exports costs nothing. The credits guide covers plans, rollover, overage and top-ups.

Errors and rate limits

Every error has the same shape: a stable code to branch on, a readable message, optional detail, and the request_id to quote if you contact us.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to start this run",
    "detail": {
      "required": 25,
      "available": 10,
      "shortfall": 15
    },
    "request_id": "6c1d1f0e-2a7b-4f3e-9b8a-0d4e5f6a7b8c"
  }
}

Limits are per workspace and depend on the plan. Rate-limited responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). A 429 rate_limit_exceeded adds Retry-After in seconds; wait that long before trying again.

If an operation is not present in the supported reference, keep it out of the launch path and start with a new report brief.