Get data¶

All endpoints on this page accept a project API key in Authorization: Bearer <key>. Use the project ID associated with that key. The literal /v1/key path prefix is part of these request URLs.

export API_BASE="https://api.azscraper.com"
export API_KEY="<project-api-key>"
export PROJECT_ID="<project-id>"

Supported marketplaces¶

GET /public/marketplaces returns the Amazon marketplace codes and storefront domains supported by this deployment. This public metadata endpoint does not require an API key.

curl -sS "$API_BASE/public/marketplaces"

Example response:

{
  "data": [
    { "code": "US", "domain": "www.amazon.com", "url": "https://www.amazon.com" },
    { "code": "BR", "domain": "www.amazon.com.br", "url": "https://www.amazon.com.br" },
    { "code": "MX", "domain": "www.amazon.com.mx", "url": "https://www.amazon.com.mx" }
  ]
}

Crawl jobs¶

Create a job¶

POST /v1/key/projects/{projectId}/jobs

Send a search job with keywords or a details job with ASINs or product URLs:

curl -sS -X POST "$API_BASE/v1/key/projects/$PROJECT_ID/jobs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"search","targets":["wireless earbuds"],"config":{"marketplace":"US","lang":"en-US"}}'

The response contains data.id, which you can use to check the job's status. AzScraper queues the job and charges credits based on its targets.

Create a job and wait for results¶

POST /v1/key/projects/{projectId}/jobs/sync

This endpoint accepts the same body as Create a job. For a single details ASIN, it checks the MongoDB product catalog first. A record updated within 24 hours is returned immediately without a new job. An older record is returned immediately while a low-priority (5) refresh job is queued. If no record exists, a high-priority (1) job is queued and the request polls the worker's temporary Redis result key for up to 10 seconds. The worker persists valid product details to MongoDB before publishing them to Redis; the Redis key expires after 60 seconds and only bridges the worker to the waiting request. If the worker finishes without a Redis result, the endpoint returns the job result already stored in MongoDB. Other request shapes create a normal queued job and wait for its terminal status for up to 10 seconds.

When Amazon confirms the ASIN is not found, the response contains a result row with found: false and status: "not_found" instead of waiting for a Redis result that will not be published.

curl --max-time 12 -sS -X POST "$API_BASE/v1/key/projects/$PROJECT_ID/jobs/sync" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"details","targets":["B08N5WRWNW"],"config":{"marketplace":"US","lang":"en-US"}}'

Successful response:

{
  "data": [{ "asin": "B08N5WRWNW", "title": "Example product", "price": 29.99 }],
  "meta": { "total": 1, "offset": 0, "limit": 1, "hasMore": false, "complete": true },
  "job": { "id": "67e3...", "status": "queued" },
  "cache": { "hit": false, "stale": false, "refreshQueued": false }
}

Cache responses include the same data and meta fields plus cache. A stale cache response has cache.hit: true, cache.stale: true, and cache.refreshQueued: true; its job is the low-priority refresh. Fresh cache responses do not include a job. A cache miss returns the queued job alongside the Redis result when it arrives.

On timeout, the request returns HTTP 504 with error code CRAWL_TIMEOUT and the job ID. The job remains queued or running and continues to consume credits according to its targets. Use GET /v1/key/jobs/{jobId} to poll it, then GET /v1/key/jobs/{jobId}/results after completion. Do not automatically retry a timed-out request because its job is still running.

List jobs for a project¶

GET /v1/key/projects/{projectId}/jobs

Optional query parameters:

curl -sS "$API_BASE/v1/key/projects/$PROJECT_ID/jobs?status=completed&limit=20&offset=0" \
  -H "Authorization: Bearer $API_KEY"

Get a job¶

GET /v1/key/jobs/{jobId}

Job statuses are queued, running, completed, failed, and cancelled. Poll with a few seconds between requests rather than tight-looping.

curl -sS "$API_BASE/v1/key/jobs/$JOB_ID" \
  -H "Authorization: Bearer $API_KEY"

Get result rows¶

GET /v1/key/jobs/{jobId}/results

Returns the job's stored result items. Each item's fields depend on whether the job searched by keyword or crawled product details.

Export results¶

GET /v1/key/jobs/{jobId}/export?format={json|csv|llm}

The response is a file download. The default format is json; csv returns a CSV file, and llm returns normalized, versioned JSON. The job must be complete before you can export it.

curl -sS "$API_BASE/v1/key/jobs/$JOB_ID/export?format=csv" \
  -H "Authorization: Bearer $API_KEY" \
  -o results.csv

See LLM-ready export for the normalized JSON contract.

Retry or cancel a job¶

Send the same Bearer header with either request. A retry creates a new job and consumes credits for its targets.

Project analytics¶

GET /v1/key/projects/{projectId}/analytics

Use the optional from and to query parameters to select a date range. Values can be ISO timestamps or YYYY-MM-DD. By default, the range covers the last 30 days and ends now.

curl -sS "$API_BASE/v1/key/projects/$PROJECT_ID/analytics?from=2026-09-01&to=2026-10-01" \
  -H "Authorization: Bearer $API_KEY"

Schedules¶

Schedules create recurring crawl jobs in the project associated with the API key. Cron expressions use UTC.

Create request example:

{
  "cron": "0 9 * * *",
  "crawlConfig": {
    "type": "details",
    "targets": ["B08N5WRWNW"],
    "config": { "marketplace": "US", "lang": "en-US" }
  }
}

crawlConfig uses the same type, targets, and optional config fields as Create a job.

Change tracking¶

These endpoints return monitored products and compare crawl snapshots within the project associated with the API key:

Endpoint summary¶

For webhook configuration and delivery, see Webhooks.