# Plans & access

> What each plan includes, and what a 403 for a missing entitlement looks like.

Source: https://api.tailend.dev/docs/plans-and-access

Check here whether a feature is available on your key before you build on
it, and what the API returns when it is not. Every endpoint's reference page
shows its access requirement, and the [OpenAPI spec](https://api.tailend.dev/docs/openapi.json)
records it as `x-access` (endpoints) and `x-access-addons` (`include=` values).

```bash
curl -sS -H "X-API-Key: $TAILEND_API_KEY" --get https://api.tailend.dev/v1/philadelphia/events \
  --data-urlencode "include=source"
```

```javascript
const res = await fetch("https://api.tailend.dev/v1/philadelphia/events?include=source", {
  headers: { "X-API-Key": process.env.TAILEND_API_KEY },
});
if (res.status === 403) {
  const { error } = await res.json();
  console.log(error.code, error.details.upgrade_url); // "include_not_permitted", "https://tailend.dev/pricing"
}
```

## Plans

A customer key is on one of three plans: `free`, `standard` or `partner`.
See [Entitlements](#entitlements) below for what each one includes.

> **TODO (owner):** add each plan's price, monthly request allowance and
> per-minute rate limit, or link the pricing page. These docs do not state
> numbers that are not published yet.

## Current truth

| What | Access today |
| --- | --- |
| Existing `/v1` operations | `all` plans. |
| Upcoming listing history | Feature `history`: included with partner; available as an add-on on standard; not available on free. |
| Upcoming trends | Feature `trends`: included with partner; available as an add-on on standard; not available on free. |
| Upcoming insights (beta) | Feature `insights`: included with partner; available as an add-on on standard; not available on free. |
| `include=source` | Included with partner; available as an add-on on standard; not available on free. |
| `include=related` | Included with partner; available as an add-on on standard; not available on free. Single-listing reads only. |

`facets=` (counts over a whole filtered set) is available on every plan and counts as one request, however many listings it covers. This is a deliberate choice, not an oversight: facets are not a premium feature. To keep the service responsive, a burst of facet requests may be answered with `is_complete: false` (partial counts) rather than slowing other traffic. See [Market overview with facets](https://api.tailend.dev/docs/market-overview-with-facets.md).

## Include add-ons

Ask for `include=source` without an entitled key and you get `403 include_not_permitted`, naming the add-on and `https://tailend.dev/pricing` in `details`. Add `include_mode=lenient` and the same request succeeds instead: `200`, with the block left off and the omission recorded in `notices[]`, including the same `upgrade_url`. See [Shaping responses](https://api.tailend.dev/docs/shaping-responses.md) for the full request/response shapes.

## Premium endpoints

A key without the effective entitlement receives `403 feature_not_in_plan`; `details.feature` names the missing feature and `details.upgrade_url` is `https://tailend.dev/pricing`.

```json
{
  "error": {
    "code": "feature_not_in_plan",
    "message": "feature 'history' is not included with this key's plan",
    "details": { "feature": "history", "upgrade_url": "https://tailend.dev/pricing" },
    "request_id": "req_2c6a19f8d0b34e77"
  }
}
```

There's no `include_mode=lenient` equivalent for a premium *endpoint* the
way there is for a premium `include=` add-on — a `feature_not_in_plan` 403
is always hard. `include_mode=lenient` only ever softens an `include=`
value on an operation you're already allowed to call (see
[Include add-ons](#include-add-ons) above).

## Entitlements

What a key can use is its plan's defaults plus any add-ons granted to that key. Partner includes `history`, `trends`, `insights` and `source`. Standard includes none of them by default, and each can be added to a key. Free cannot add premium features. When an add-on is removed from a key, requests that need it get the responses above: `403` for a premium endpoint, and for an `include=` add-on either `403` or, with `include_mode=lenient`, a `200` without that block.

## What to do

- Check the badge on an operation or add-on before you build against it, but always branch on `error.code` at runtime.
- Building against `include=source`? Confirm your key is entitled before you rely on it in production; use `include_mode=lenient` during development so a missing entitlement degrades instead of failing outright.
- See [Limits & usage](https://api.tailend.dev/docs/limits-and-usage.md) for the separate question of *how much* you can call, as opposed to *what* you can call.