Sample responses¶

These examples use a project API key. Set API_BASE, API_KEY, and PROJECT_ID as described in Get started.

Create a search job¶

POST /v1/key/projects/{projectId}/jobs
Authorization: Bearer <project-api-key>
Content-Type: application/json

{
  "type": "search",
  "targets": ["wireless earbuds"],
  "config": { "marketplace": "US", "lang": "en-US" }
}

Example response:

{
  "data": {
    "id": "67e3...",
    "projectId": "67d2ab...",
    "type": "search",
    "status": "queued",
    "targets": [{ "value": "wireless earbuds", "status": "pending" }],
    "config": { "marketplace": "US", "lang": "en-US" },
    "createdAt": "2026-10-08T03:05:00.000Z"
  }
}

Use the returned data.id to check the job's status.

Get a job¶

GET /v1/key/jobs/{jobId}
Authorization: Bearer <project-api-key>

{
  "data": {
    "id": "67e3...",
    "projectId": "67d2ab...",
    "type": "search",
    "status": "completed",
    "targets": [{ "value": "wireless earbuds", "status": "success" }],
    "resultSetId": "67e4...",
    "createdAt": "2026-10-08T03:05:00.000Z",
    "completedAt": "2026-10-08T03:06:14.000Z"
  }
}

Get result rows¶

GET /v1/key/jobs/{jobId}/results
Authorization: Bearer <project-api-key>

{
  "data": [
    { "asin": "B08N5WRWNW", "title": "Example product", "price": 29.99 }
  ],
  "meta": { "total": 1 }
}

The fields in each result depend on the crawl type and the data Amazon returns.

Download an export¶

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

The export is returned as a file, not in a { "data": ... } JSON envelope. Supported formats are json, csv, and llm.

Error response¶

If a request is invalid or the key cannot access the resource, the API returns this error envelope:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "No access to this project",
    "details": []
  }
}

Use error.code to handle the error in your integration. See Error taxonomy.