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

# Credits & access

> What each endpoint costs, which APIs your key can call, and where to see your balance.

Your plan bundles a number of **credits** per billing period. Each paid request
deducts a fixed number of credits. Free endpoints deduct nothing. Denied and
rate-limited requests are never billed: metering happens only after authentication,
the access check and the rate limit have all passed.

## Cost per endpoint

| API               | Endpoint                                        | Credits                     |
| ----------------- | ----------------------------------------------- | --------------------------- |
| Real-time stream  | `wss://…/eventory/notifications/subscribe`      | **0**                       |
| Watchlist         | `GET`, `POST`, `PATCH`, `DELETE /watchlist…`    | **0**                       |
| Account           | `GET /usage`                                    | **0**                       |
| Market Data       | `POST /eventory/data/search`                    | **1**                       |
| Market Data       | `GET /eventory/data/viagogo/{event_id}`         | **1**                       |
| Market Data       | `GET /eventory/data/sales/viagogo/{event_id}`   | **1 per 20 rows** requested |
| Market Data       | `GET /eventory/data/ticketmaster/{tm_event_id}` | **1**                       |
| Market Data       | `GET /eventory/data/artist`                     | **1**                       |
| Market Data       | `POST /eventory/data/events/add`                | **1**                       |
| Market Data       | `GET /eventory/data/ping`                       | **1**                       |
| Live Availability | `POST /events/scrape`                           | **5**                       |
| Live Availability | `GET /events/platforms`                         | **5**                       |
| Live Availability | `GET /events/ping`                              | **5**                       |

<Note>
  The sales list is the one endpoint priced by quantity. Its cost is
  `ceil(sales_limit / 20)`: the default 20 rows cost 1 credit, 100 rows cost 5, the
  maximum of 200 rows costs 10. A `sales_limit` outside `1..200` is rejected with
  `400 invalid_parameter` before anything is charged.
</Note>

The ping endpoints are billed like any other call on their API. To test a key for
free, use `GET /usage`.

## Included, purchasable, or on request

| API                | Access                                                              |
| ------------------ | ------------------------------------------------------------------- |
| Real-time stream   | Included with every plan.                                           |
| Watchlist          | Included with every plan.                                           |
| Account (`/usage`) | Included with every key, whatever else it is granted.               |
| Market Data        | Enabled per account. Purchasable as part of a plan or as an add-on. |
| Live Availability  | Enabled per account, on request.                                    |

Each key carries the list of APIs it may call. Calling an API your key is not granted
returns `403 forbidden` regardless of your credit balance. To enable an API on your
key, contact Eventory.

## Included quota versus hard cap

Two numbers from `GET /usage` matter:

* **`credits.included`** is the quota bundled into your plan for the period. Going
  past it does not block you; usage beyond it is billed as overage.
* **`credits.hard_cap`** is where the gateway stops serving. Once `credits.used`
  reaches it, every paid request returns `402 limit_reached` until the period resets
  or the cap is raised. Free endpoints keep working. A cap of `"unlimited"` means
  there is no ceiling.

`usage_status` folds this into one field you can switch on:

| `usage_status`      | Meaning                                       |
| ------------------- | --------------------------------------------- |
| `ok`                | Under 80% of the included quota.              |
| `approaching_limit` | At or above 80% of the included quota.        |
| `over_included`     | Past the included quota; overage is accruing. |
| `at_hard_cap`       | The gateway is refusing paid requests.        |
| `none`              | No active subscription.                       |

`credits.remaining` counts only spendable credits, so it is clamped to the hard cap.
`credits.projected_used` extrapolates your current pace to the end of the period.

```bash theme={null}
curl -s https://api.eventory.ai/usage -H "apikey: $EVENTORY_API_KEY"
```

```json theme={null}
{
  "plan": "basic",
  "status": "active",
  "usage_status": "ok",
  "period": { "start": "2026-06-01T00:00:00Z", "end": "2026-07-01T00:00:00Z", "days_remaining": 19, "elapsed_fraction": 0.3771 },
  "credits": { "included": 5000, "used": 1234, "remaining": 3766, "overage": 0, "percent_used": 24.68, "projected_used": 3272, "hard_cap": 6000, "in_overage": false }
}
```

## Subscription state

Only `active` and `trialing` subscriptions are served. A paused, cancelled, unpaid or
past-due subscription returns `402 no_subscription` on every paid endpoint. `GET /usage`
still answers, with `"status": "none"` and zeroed credits, so you can detect the
situation programmatically.

## Keeping costs down

* **Cache `GET /events/platforms`.** The registry changes rarely and costs 5 credits.
* **Prefer the stream to polling.** Watching an event is free; scraping it every
  minute is 5 credits a minute.
* **Request only the sales rows you need.** `sales_limit=40` costs 2 credits;
  `sales_limit=200` costs 10.
* **Do not retry `4xx` responses.** They are billed once and will fail again.
  Retry only `5xx`, and with backoff.