Making a request

Name the endpoint in the path, pass its parameters in params, and read the JSON back. Two path styles cover direct calls and persisted, dataset-backed runs.

Two path styles

Every extractor is reachable two ways. Pick based on whether you want the result stored:

/v1/{platform}/{action} the direct, synchronous call. You get the data inline in the response. Most actions are POST; a few read-only ones are GET. Path parameters may appear, for example /v1/reddit/posts/{post_id}/comments.
/v1/data/{platform}/{action} the persisted wrapper. It runs the same extractor, bills the same, and also writes the result into your dataset store with 7-day retention so you can fetch it again by job id.

Request body

The body is a small envelope around your endpoint parameters.

Field	Description
`clientKey`	Your Data API key, if not passed via the X-API-Key header. See Authentication.
`params`	Object of endpoint-specific parameters (e.g. query, domain, page). The playground lists the params for each endpoint.
`freshness`	"auto" (default), "cached", or "fresh". auto serves a recent cached result when one exists; cached only returns a cached hit; fresh forces a new extraction.

freshness controls cost and speed

auto reuses a recent cached extraction when it exists, which is faster and can return status: “cached”. Use fresh when you need real-time data and are willing to pay for a new run.

Example: amazon/search

request.sh

curl -s https://api.capzy.ai/v1/amazon/search \
  -H 'X-API-Key: capzy_data_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "params": { "query": "usb c cable", "domain": "com", "page": 1 },
    "freshness": "auto"
  }'

Response shape

A successful synchronous call returns errorId: 0 with the data and billing metadata. When more pages are available, nextCursor is present.

response.json

{
  "errorId": 0,
  "status": "ready",
  "jobId": "d1f9c2a0-...",
  "data": { "results": [ /* source-shaped rows */ ] },
  "itemCount": 48,
  "credits": 1,
  "cost": "0.03000",
  "nextCursor": "eyJwYWdlIjoyfQ"
}

Any failure returns a non-zero errorId with a machine-readable code:

error.json

{
  "errorId": 1,
  "errorCode": "ERROR_ENDPOINT_BLOCKED",
  "errorDescription": "The target could not be reached for this request."
}

Response headers

Billing and pagination metadata also ride on the response headers:

X-Credits-Used integer credits billed for this run.
X-Data-Cost the USD cost, to five decimal places.
X-Next-Cursor the cursor for the next page, mirroring nextCursor in the body when present.

Batch requests

The persisted wrapper accepts a batch: append /batch and pass a queries array of param objects. Each query becomes its own job, billed independently.

Field	Description
`queries`	Array of param objects, one per item. Each becomes its own job, billed independently.
`freshness`	Applies to every query in the batch. Same values as the single-request field.

batch.sh

curl -s https://api.capzy.ai/v1/data/amazon/search/batch \
  -H 'X-API-Key: capzy_data_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "queries": [
      { "query": "usb c cable" },
      { "query": "hdmi 2.1 cable" },
      { "query": "displayport cable" }
    ],
    "freshness": "auto"
  }'

Jobs & polling read persisted results and page through large sets.
Endpoint catalog find the platform and action you need.

Authentication

Jobs & polling