Jobs & polling

Persisted runs create a job you can poll by id. Results are retained for 7 days, and large result sets page through a cursor.

Lifecycle

A run moves through a small set of states. Direct /v1/{platform}/{action} calls usually complete inline and hand you the data in the response. Persisted runs via /v1/data/{platform}/{action} return a jobId you can look up later.

Status	Description
`pending`	Accepted and queued, not yet started.
`running`	The extraction is in progress.
`completed`	Finished successfully. Results are available.
`cached`	Served from a recent cached extraction rather than a new run.
`failed`	The run did not succeed. See the error field. Failed runs are not billed.

No webhooks

The Data API does not send callbacks. To track an async or scheduled run, poll the job status endpoint until status is completed, cached, or failed.

Polling a job

Fetch a job with GET /v1/data/jobs/{job_id}. The clientKey is required on this call so the lookup is scoped to your account. You may pass it as the clientKey query parameter shown here, or via the X-API-Key header.

poll.sh

curl -s 'https://api.capzy.ai/v1/data/jobs/d1f9c2a0-...?clientKey=capzy_data_YOUR_KEY'
# -> {
#   "errorId": 0,
#   "jobId": "d1f9c2a0-...",
#   "status": "completed",
#   "platform": "amazon",
#   "action": "search",
#   "itemCount": 48,
#   "credits": 1,
#   "cost": "0.03000",
#   "nextCursor": "eyJwYWdlIjoyfQ",
#   "error": null
# }

Job response

Field	Description
`jobId`	The job identifier you polled.
`status`	One of pending, running, completed, cached, or failed.
`platform / action`	The endpoint this job ran.
`itemCount`	Number of records the run produced.
`credits / cost`	Credits billed and the USD cost. Zero for failed runs.
`nextCursor`	Cursor for the next page, when more results exist.
`error`	Failure detail when status is failed, otherwise null.

7-day retention

Completed results stay available for 7 days, then age out. Fetch and store anything you need to keep beyond that window.

Pagination

When a result set spans multiple pages, the response includes a nextCursor in the body and an X-Next-Cursor header. Pass that value back as the endpoint's cursor parameter to fetch the next page. When there is no next cursor, you have reached the end.

paginate.py

import requests

API = "https://api.capzy.ai"
KEY = "capzy_data_YOUR_KEY"

cursor = None
while True:
    params = {"query": "usb c cable"}
    if cursor:
        params["cursor"] = cursor
    r = requests.post(
        f"{API}/v1/amazon/search",
        headers={"X-API-Key": KEY},
        json={"params": params},
    )
    body = r.json()
    handle(body["data"])
    cursor = r.headers.get("X-Next-Cursor")
    if not cursor:
        break

Queues & schedules run many jobs automatically.
Pricing how runs are billed.

Making a request

Queues & schedules