Skip to main content
Every Scenario Method is one HTTP call:
The body is a JSON object with the method’s parameters. The response is always a JSON envelope — see Responses.

​
Endpoints

Catalog, describe and the OpenAPI document never need a key, so you can read the whole contract before you spend a credit.

​
Authentication

Send your master key as a bearer token:
The same ak_... key you use for the MCP server works here. A missing or invalid key returns 401. See Authentication.

​
Request body rules

  • The body must be a JSON object, at most 1 MB. Larger bodies return 413.
  • Schemas are strict. A field the method does not declare is rejected with 400 and error_type: "validation" — nothing is silently ignored, so a typo or an upstream parameter name never slips through.
  • Every parameter has a type, and enums are enforced. Defaults are applied on the server (limit defaults to 20 on paged methods).
  • The exact schema of a method is on its page in the sidebar, in GET /v2/ops/{method} as input_schema, and in the OpenAPI document.

​
Shared parameters

Parameters keep the same name and meaning across methods. Which ones a given method accepts, and the valid values, are on the method’s page. E-commerce methods add price_min / price_max, region, currency and platform filters; finance methods add start / end, period, statement, interval. These are typed and documented per method.

​
Reserved parameters

Four parameters exist on every method. They control routing and the shape of the response, not what the method does.
​
object
Override provider selection: order, only, allow_fallbacks, strategy. Details in Routing & Pricing.
​
string
Shorthand for routing.only = [provider] — pin the call to one provider.
​
string[]
Return only these dotted paths of data, e.g. ["items.id", "items.text", "items.metrics.likes"]. Use it to keep responses small for an LLM context. raw is not affected.
​
boolean
default:"false"
Attach the upstream provider’s payload as raw. It is not part of the contract and may change whenever the provider changes; payloads above 256 KB are truncated and flagged with raw_truncated: true.

​
Pagination

Methods that return a list (PostPage, ProductPage, UserPage, …) page with an opaque cursor:
  1. Call the method without cursor. The response’s data.next_cursor is a string when more results exist, null when they don’t.
  2. Call again with the same parameters plus cursor.
Two rules follow from how cursors work:
  • A cursor is bound to the provider that produced the first page, so later pages come from the same provider and stay consistent. If that provider fails on a later page, the call fails rather than silently switching.
  • A cursor is bound to the query. Reusing it with a different query (or other parameters) returns 400.
A limit smaller than the provider’s own page size is fine: the server keeps reading the same upstream page across your calls, so nothing is skipped. Methods without pagination (single-object lookups) have no cursor and no next_cursor.

​
Example

Search X for recent posts, keep three fields and page through the results:
Then, with the next_cursor from the response: