Introduction

The base URL for all endpoints is:

https://api.amazonomics.com

All endpoints need an API key in the Authorization header. See Authentication.

Response format

Every JSON response has a data field and an error field. Exactly one of them is set:

{
  "data": [ ... ],
  "error": null
}

On failure, data is null and error describes the problem:

{
  "data": null,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Provide at least one valid ASIN.",
    "hint": "ASINs must be 10 characters."
  }
}

The hint field is optional. The export endpoints are the exception to this format: they return an XLSX file.

Pagination

List endpoints accept page and limit query parameters. The response includes a pagination object:

{
  "pagination": {
    "current_page": 1,
    "page_size": 50,
    "total_count": 128,
    "total_pages": 3,
    "has_next": true,
    "has_previous": false
  }
}

Periods

Rank history uses period keys. Monthly keys use the MM-YYYY format, for example 07-2026. Weekly keys use the WW-YYYY format with ISO week numbers, for example 31-2026. Your plan sets the monthly window: the last 24 periods on Pro, all periods on Studio. Weekly data covers the last 6 weeks on all plans. Use GET /v1/periods to list the periods that your plan can access.

Rate limits

The search endpoints (/v1/search/asin and /v1/search/keywords) have a rate limit. The limit applies to your whole organization, on a rolling one-hour window:

Plan	Searches per hour
Pro	100
Studio	500

Each search response includes these headers:

Header	Meaning
`RateLimit-Limit`	Your hourly limit.
`RateLimit-Remaining`	Requests left in the current window.
`RateLimit-Reset`	Unix time (seconds) when the window resets.

If you go over the limit, the API returns status 429 with code RATE_LIMIT_EXCEEDED and a Retry-After header. Wait that many seconds, then retry.

Error codes

Status	Code	Cause
400	`INVALID_PARAMETERS`	A query parameter is missing or not valid.
400	`NO_ACTIVE_SUBSCRIPTION`	Your organization has no active subscription.
401	`UNAUTHORIZED`	The API key is missing, wrong, or disabled.
403	`FORBIDDEN`	The key is not allowed to do the action.
429	`RATE_LIMIT_EXCEEDED`	You went over your hourly search limit.
500	`INTERNAL_SERVER_ERROR`	Something failed on our side. Retry later.

API reference

Endpoints

Response format

Periods

Rate limits

Error codes

​Response format

​Pagination

​Periods

​Rate limits

​Error codes

Response format

Pagination

Periods

Rate limits

Error codes