Plans & 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 records it as x-access (endpoints) and x-access-addons (include= values).

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

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 below for what each one includes.

#Current truth

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.

#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 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.

{
  "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 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 for the separate question of how much you can call, as opposed to what you can call.