Research jobs

List the authenticated organization's research jobs, newest first. Paginated.

Submit between 1 and 100 domains for a full read on every name. 10 credits per uncached domain. Cached domains return their existing report immediately at no cost. The Idempotency-Key header is required - reusing a key within 24 hours returns the original job.

Submit 1-100 domains for quick reads. Each name goes through a fast routing pass that decides whether the full appraisal is worth it:

• Quick read (read_type="quick") - the routing pass judged the name not worth the full appraisal. You get a first-pass wholesale / aftermarket / brokered estimate plus a one-sentence rationale. 1 credit per name.
• Full read (read_type="full") - the routing pass judged the name worth the deep appraisal, which runs end to end (every signal, every probe, every recommendation). 10 credits per name.

The job returns 202 immediately; the per-name decisions land asynchronously. Poll GET /v1/research-jobs/{id} until counts.pending and counts.running reach 0.

Credits are reserved at the worst case (10 per uncached name) and the running total settles down as quick reads come back. credits_charged on the job payload is the authoritative running total - always reflects what your wallet actually paid.

Idempotency-Key works the same as the full endpoint.

The POST /v1/research-jobs endpoint (without /quick) is unchanged - every domain runs the full appraisal at 10 credits each, no routing involved.

Force a fresh appraisal on one domain. Default body is empty (full read, 10 credits). Pass {"quick": true} to use the same routing pass the quick endpoint uses (1 credit if the routing pass returns a quick read, 10 credits if it judges the name worth the full appraisal).

Unlike the cached read of GET /v1/domains/{domain}/pricing, this endpoint always runs a fresh appraisal - useful when you want to refresh a stale result or upgrade a quick read to the full appraisal. The new result overwrites the prior one for future reads of /v1/domains/{domain}/pricing and the report endpoints (a full read always overrides a quick read for the same name; the earlier entry stays in your history).

This is the API equivalent of the dashboard's "Run full read" upgrade button. Customers who got a quick read in a bulk job can upgrade individual names without resubmitting the whole job.

Stops a running job. Returns whatever credits were still reserved for names that hadn't finished yet - names that already came back keep their charge (10 credits for a full read, 1 for a quick read). The response carries credits_refunded so you can see exactly how much landed back in your wallet. Idempotent: calling it on an already-terminal job returns 409.

Returns every domain in the job with its current job_status and (when computed) its full DomainReport. Customers poll this during a running job to watch reports fill in; once terminal, it's a one-shot answer for 'give me everything from this submission.'

Domains in pending or running status carry only domain + job_status — no report key (the omit-when-null contract). paid and cached domains carry the full DomainReport. failed domains carry an error code (see "Error codes" in the docs).

Pricing-only variant of /v1/research-jobs/{id}/report. Each entry carries the price band (wholesale / aftermarket / brokered), reasoning, key factors, and risks - capped at 4 KB per text field. Faster and lighter than the full report wrapper; built for the 'CSV of just the dollars and reasoning' workflow without pulling the probes / signals / brand signals you don't need.

Pass ?format=csv to receive a browser-downloadable CSV instead of JSON. The CSV contains one row per domain in the job, with the same data as the JSON response projected into a flat row format. Failed entries occupy a row with the error column populated and the dollar columns blank.