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

> ## Agent Instructions
> Base URL: https://api.eventory.ai. Send your API key in the apikey header. Market Data and Live Availability calls cost credits, pings included; GET /usage is free, so use it to test a key. Costs per endpoint: https://eventory.ai/docs/credits-and-access.md

# API credit costs per endpoint

> 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 |
| - | - | - |
| Notifications API | `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/vividseats/{production_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.

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 |
| - | - |
| Notifications API | Not included in any API plan. Granted separately, to a limited number of partners. |
| 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. A paid request is
  refused with `402 limit_reached` when its cost would take usage past the cap, so
  near the cap a 5-credit scrape can be refused while 1-credit calls still pass. At
  the cap, every paid request is refused 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` is what is left of the included quota (or of the hard cap, if that
is lower). It reads `0` once you are in overage, even though paid requests keep being
served until the hard cap. `credits.used` can trail your most recent requests by a
minute or so.
`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.
A plan without API credits, such as Monitors Essential, is answered the same way.

## Keeping costs down

* **Cache `GET /events/platforms`.** The registry changes rarely and costs 5 credits.
* **If you have Notifications API access, prefer it to polling.** Watching an event
  deducts no credits; 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`, with backoff: each retry is billed like a new request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.