Skip to main content
POST
research.sources.extract

Authorizations

Authorization
string
header
required

API key: sk_live_…

Headers

Idempotency-Key
string

Optional. A retry with the same key returns the stored result.

Maximum string length: 255
Pramaan-Max-Price-Micro
string

Optional. The most this request may be priced at, in micro-USD (a whole number above 0). It replaces the capability's own price ceiling for this request, lower or higher. Sources that could cost more are left out; when none is left the answer is 400 with the lowest limit that would work.

Pattern: ^[1-9]\d{0,14}$

Body

application/json
rows
object[]
required

The rows to research, 1 to 100.

Required array length: 1 - 100 elements
schema
object

Optional JSON Schema of the fields to fill in per row: an object of 1-8 named scalar, enum or short-array fields. Without it, each row returns a written report.

tier
enum<string>
default:quick

How deep each row researches: quick $0.005, basic $0.01, standard $0.025, thorough $0.05, deep $0.10, deeper $0.30, extensive $0.60, extensive-4x $1.20, exhaustive $2.40 per row - at the 100-row cap up to $0.50 (quick) or $240 (exhaustive). The job starts only when the credit covers its worst case. Failed rows are not billed.

Available options:
quick,
basic,
standard,
thorough,
deep,
deeper,
extensive,
extensive-4x,
exhaustive
dataSources
object

Partner data sources the rows may draw on, besides the live web.

ownServers
object[]

Your own tool servers the rows may call during research. The research service contacts them while a run executes; name each one and the report cites it by that name. Servers must be public https and accept unauthenticated calls: sending credentials (headers) to them is not supported yet, because a job's request is stored and secrets must not be.

Maximum array length: 3
includeDomains
string[]

Only pages on these domains are used.

Maximum array length: 20
Required string length: 1 - 253
excludeDomains
string[]

Pages on these domains are not used.

Maximum array length: 20
Required string length: 1 - 253
afterDate
string

Only pages published on or after this date are used.

Pattern: ^\d{4}-\d{2}-\d{2}$

Response

Job started; poll GET /v1/jobs/{id}

job_id
string
required
status
enum<string>
required
Available options:
running
held_micro
integer
required

The credit set aside for the job (its estimate), micro-USD; 0 when it takes none. Not a price: what the job is charged reads on GET /v1/jobs/{id} once it is settled.