> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amazonomics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Base URL, response format, rate limits, and errors

The base URL for all endpoints is:

```
https://api.amazonomics.com
```

All endpoints need an API key in the `Authorization` header. See [Authentication](/authentication).

## Response format

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

```json theme={null}
{
  "data": [ ... ],
  "error": null
}
```

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.    |