GET/v1/{metro}/events/calendarall plans

Event counts per day

For each local date in [from, to] (both required, at most 62 days inclusive), how many event occurrences start that day, how many of them are free, and how many fall in each category — every date included, with zeros. Occurrences are exactly the ones /v1/{metro}/events lists with occurrences=expand under the same filters, so a month view's counts always agree with the week or day list behind them.

Takes the same filters as /events. weekday, start_after, start_before and season apply to each occurrence. cursor, page, fields, expand, changed_since, q and facets are not available.

include=forecast (a paid add-on, entitled as on /events) adds a forecast to today and each of the next seven days.

Try this requestRun it with sample data, no key needed. Paste a key to run it live.

Example request

curl -sS \
  -H "X-API-Key: $TAILEND_API_KEY" \
  "https://api.tailend.dev/v1/philadelphia/events/calendar?from=2026-10-01&to=2026-10-31"

Example response · 200

{
  "data": [
    {
      "date": "2026-10-05",
      "count": 41,
      "free_count": 22,
      "categories": {
        "storytime_books": 14,
        "arts_creative": 9,
        "sports_active_play": 6
      }
    },
    {
      "date": "2026-10-06",
      "count": 0,
      "free_count": 0,
      "categories": {}
    },
    {
      "date": "2026-10-07",
      "count": 57,
      "free_count": 31,
      "categories": {
        "storytime_books": 19,
        "music_movement": 8
      },
      "forecast": {
        "summary": "Chance Showers",
        "temperature_f": {
          "min": 54,
          "max": 66
        },
        "precipitation_chance_max": 60,
        "wet_hours": [
          [
            13,
            16
          ]
        ],
        "issued_at": "2026-10-05T14:00:00Z",
        "expires_at": "2026-10-05T15:00:00Z"
      }
    }
  ],
  "meta": {
    "metro": "philadelphia",
    "window": {
      "from": "2026-10-05",
      "to": "2026-10-07",
      "timezone": "America/New_York"
    },
    "min_confidence": 0.7,
    "total": 98,
    "applied_filters": {
      "from": "2026-10-05",
      "to": "2026-10-07",
      "min_confidence": 0.7,
      "audience": [
        "not_adults"
      ]
    },
    "defaults_applied": [
      "min_confidence",
      "audience"
    ],
    "generated_at": "2026-10-07T12:00:00.000Z"
  }
}

API key Remember for this tab

Try any request with sample data, no key needed. Available on every plan.

metrostringrequiredpath

Metro slug from /v1/metros (e.g. philadelphia).

fromstring (date)requiredquery

First local date of the window, YYYY-MM-DD.

tostring (date)requiredquery

Last local date of the window (inclusive), at most 61 days after from.

Optional parameters (25)

min_confidencenumberoptionalquery

Drop rows whose confidence is below this.

categoryarray of stringoptionalquery

Keep rows whose categories contain any of these.

audiencearray of stringoptionalquery

Keep rows whose audience is one of these.

seasonarray of stringoptionalquery

Events, classes and camps only.

occasionstringoptionalquery

Events and classes tagged for a seasonal occasion.

teamstringoptionalquery

Events built around a local pro sports team (watch parties, game-day themed events, team or mascot appearances).

ageintegeroptionalquery

A child's age in years.

neighborhoodstringoptionalquery

Neighborhood slug or free-text name (case-insensitive).

latnumberoptionalquery

Center latitude for a radius search.

lngnumberoptionalquery

Center longitude for a radius search.

radius_mintegeroptionalquery

Radius in metres around lat/lng (or near_zip, where enabled).

ziparray of stringoptionalquery

Beta — may not be enabled for all keys yet.

near_zipstringoptionalquery

Beta — may not be enabled for all keys yet.

include_approximatebooleanoptionalquery

Beta — may not be enabled for all keys yet.

place_idstring (uuid)optionalquery

Keep rows held at this place (place.id).

freebooleanoptionalquery

Events, classes, and camps only; ignored for places.

has_timebooleanoptionalquery

true keeps only events with a stated clock time.

recurringbooleanoptionalquery

Filter on is_recurring.

weekdayarray of stringoptionalquery

Keep rows on any of these local days.

start_afterstringoptionalquery

Local start time at or after this, HH:MM (or HH:MM:SS).

start_beforestringoptionalquery

Local start time strictly before this, HH:MM; 09:00–12:00 is the morning and 12:00 belongs to the afternoon.

max_pricenumberoptionalquery

A budget.

organization_idstring (uuid)optionalquery

Keep rows published by this organization (organization.id).

includearray of stringoptionalquery

Opt into a block the lean default response leaves out.

include_modestringoptionalquery

How an include= the key is not entitled to is handled.

Response

A 200 returns application/json with these fields.

dataarray of CalendarDayalways present
One entry per date in [from, to], in order, including dates with no occurrences.
- datestring (date)always present
  A local date in the metro's timezone.
- countintegeralways present
  Occurrences starting on this date — exactly the items /events?occurrences=expand lists for it under the same filters.
- free_countintegeralways present
  How many of count are free.
- categoriesobjectalways present
  Occurrences per category slug on this date. An occurrence with several categories counts toward each; categories with no occurrences are left out.
- forecastCalendarDayForecast
  Present with include=forecast (a paid add-on) on today and each of the next seven days, when forecast data covers the whole day. The forecast is for the metro's centre.
  - issued_atstring (date-time)always present
    When this forecast was issued (UTC).
  - expires_atstring (date-time)always present
    When this forecast stops being fresh (UTC). The response's Cache-Control max-age never runs past it; refetch after it.
  - summarystringalways present
    A short description of the day's weather.
  - temperature_fobjectalways present
    minnumberalways present
    maxnumberalways present
  - precipitation_chance_maxnumber · nullablealways present
    The day's highest hourly chance of precipitation, in percent.
  - wet_hoursarray of array of integeralways present
    Local [startHour, endHour) ranges, 0–24, of hours with a high chance of precipitation; adjacent hours are merged. Empty on a dry day.
metaobjectalways present
- metrostringalways present
- windowobjectalways present
  - fromstring (date)always present
  - tostring (date)always present
  - timezonestringalways present
- min_confidencenumberalways present
- totalintegeralways present
  The sum of count over the window.
- applied_filtersAppliedFiltersalways present
  The filters this response was actually computed with, as their request parameters: the value in effect for each filter the endpoint applies, whether you sent it or it came from a default. A filter that is unset (no category=, for instance) is absent, and a filter the endpoint does not apply (weekday on camps) is never listed. Always present: min_confidence and audience, plus from and to on events, classes and camps (to is null where the window is open-ended). The exception is a batch read by ids=: no window or filters apply, so only ids is listed. meta.defaults_applied names which of these came from a default.
  - fromstring (date)
  - tostring (date) · nullable
  - min_confidencenumber
  - audiencearray of string
    The audience filter in effect, in a form you can send back as audience= to get the same set. With no audience= given this is ["not_adults"]: every listing except adult-only ones. audience=all is echoed as ["all"]. A list you named is echoed as given.
    kidsfamiliesteensadultsall_agesallnot_adults
  - radius_minteger
    Present on a radius search.
  - idsarray of string (uuid)
    Present on a batch read by ids=, as the de-duplicated ids requested.
- defaults_appliedarray of stringalways present
  The names in applied_filters whose value came from a default rather than your request, for example ["from", "to", "min_confidence", "audience"]. Empty when you named every filter that has a default. A default that narrows a result (the 30-day event window, the confidence floor, the adult-audience exclusion) is listed here so a smaller-than-expected set can be explained from the response alone.
- generated_atstring (date-time)
noticesarray of Notice
Present only when there is at least one — see Notice.
- codestringalways present
  The same vocabulary as Error.code, for the same reason — branch on this, not on message.
  include_not_permittedforecast_unavailablerelated_unavailable
- includestring
  Which include= value this notice concerns.
- messagestringalways present
- upgrade_urlstring (uri)
  Where to compare plans when the omitted include is available by upgrade.

Status codes

200
One entry per date in the window.
400
Malformed or contradictory parameters (lat without lng, to before from, unknown category), or a cursor this API did not issue for this exact request — replayed from another endpoint, resource, metro or filter set, hand-crafted, or altered.
401
Missing, unknown or revoked X-API-Key. Also returned when the key record itself does not validate — the server fails closed and logs why rather than assuming anything about a row it cannot vouch for, and when the value is not shaped like a key (tl_ + 8 hex + _ + 48 hex). The message is invalid API key; the reason is not disclosed. The one exception is a credential shaped like a different kind of token, whose 401 explains it is the wrong credential for /v1 rather than repeating the generic message.
403
Two different reasons share this status. Read error.code.
Show more
forbidden — the key is valid but its scopes exclude this metro or resource type, or the client is inactive. Returned when the caller named the metro or type it was refused — in the path, or in ?metro=. Where the caller supplied only an identifier, an out-of-scope resource is a 404 instead; see NotFound.

include_not_permitted (endpoints that take include= only) — the key is valid and in scope, but is not entitled to a requested include= add-on (details.include names it). Add include_mode=lenient to get a 200 without the block instead of this. See Shaping responses.
404
No published, active resource with that id (or unknown metro).
Show more
Also returned when the resource exists but sits in a metro outside the key's scopes.metros, on the routes that take an identifier rather than a metro: /v1/{type}/{id}, /v1/{type}/slug/{slug} and /v1/organizations/{id}. The metro there is discovered from the row, not named by the caller, so a 403 would confirm that a guessed id or slug is real and say which metro it is in. The two cases are deliberately indistinguishable — same code, same message, same absent details.

Naming the metro is a different question and still gets the explicit 403 with the key's own scopes: /v1/boston/events, or ?metro=boston on a slug lookup.
405
The path exists; the method does not. Every route on this API is a read, so Allow is always GET, HEAD, OPTIONS. A method on a path that does not exist is a 404 instead — 405 is only ever sent where there is a target resource to refuse.
429
A limit was reached. Branch on error.code, not on the status — two different limits share this status:
Show more
- rate_limited — the per-minute rate. Retry-After is seconds, and retrying after it succeeds.
- rate_limited can also mean address lookups are temporarily unavailable. The response explains the condition and provides Retry-After; callers that already have coordinates can send lat/lng instead.
- quota_exceeded — the monthly allowance, or a client's hard cap. Retry-After points at the start of the next UTC month and can therefore be very large; details carries plan, monthly_limit, used and resets_at. Backing off will not help before the reset — the plan has to change. This is a 429; 402 is reserved.
500
A bug on our side. The message is always the constant internal error; details are never included in the body. Retry once with backoff, then contact support with the request_id.
501
This endpoint or feature is not available and will not become available without a configuration change — for ?address=, this means no geocoder is configured.
Show more
Nothing is failing, so do not retry and do not back off: there is no Retry-After, and the answer will not change inside any timeout you set. Treat the feature as switched off, disable it in your UI, and use the alternative the message names where there is one (lat/lng instead of address).

The message is a constant per endpoint family and names no internal object. Include the request_id when contacting support.
503
A transient outage: a dependency could not be reached or did not answer in time. This is the 5xx worth retrying — Retry-After says how long, and the same request is expected to succeed afterwards.

Like every other error here, the message names no internal detail.

Every error uses the same envelope; branch on error.code. See Errors.

Ctrl Enter to send

Request

GEThttps://api.tailend.dev/v1/philadelphia/events/calendar?from=2026-10-01&to=2026-10-31

curl -sS \
  -H "X-API-Key: $TAILEND_API_KEY" \
  "https://api.tailend.dev/v1/philadelphia/events/calendar?from=2026-10-01&to=2026-10-31"

const res = await fetch("https://api.tailend.dev/v1/philadelphia/events/calendar?from=2026-10-01&to=2026-10-31", {
  headers: { 'X-API-Key': '$TAILEND_API_KEY' },
});
const body = await res.json();
console.log(res.status, body);

import os
import requests

response = requests.get(
    "https://api.tailend.dev/v1/philadelphia/events/calendar?from=2026-10-01&to=2026-10-31",
    headers={'X-API-Key': os.environ['TAILEND_API_KEY']},
)
response.raise_for_status()
print(response.json())

ResponseSample

Showing sample data. Paste a key to run it live. Get a key

One entry per date in the window.

{
  "data": [
    {
      "date": "2026-10-05",
      "count": 41,
      "free_count": 22,
      "categories": {
        "storytime_books": 14,
        "arts_creative": 9,
        "sports_active_play": 6
      }
    },
    {
      "date": "2026-10-06",
      "count": 0,
      "free_count": 0,
      "categories": {}
    },
    {
      "date": "2026-10-07",
      "count": 57,
      "free_count": 31,
      "categories": {
        "storytime_books": 19,
        "music_movement": 8
      },
      "forecast": {
        "summary": "Chance Showers",
        "temperature_f": {
          "min": 54,
          "max": 66
        },
        "precipitation_chance_max": 60,
        "wet_hours": [
          [
            13,
            16
          ]
        ],
        "issued_at": "2026-10-05T14:00:00Z",
        "expires_at": "2026-10-05T15:00:00Z"
      }
    }
  ],
  "meta": {
    "metro": "philadelphia",
    "window": {
      "from": "2026-10-05",
      "to": "2026-10-07",
      "timezone": "America/New_York"
    },
    "min_confidence": 0.7,
    "total": 98,
    "applied_filters": {
      "from": "2026-10-05",
      "to": "2026-10-07",
      "min_confidence": 0.7,
      "audience": [
        "not_adults"
      ]
    },
    "defaults_applied": [
      "min_confidence",
      "audience"
    ],
    "generated_at": "2026-10-07T12:00:00.000Z"
  }
}

Malformed or contradictory parameters (lat without lng, to before from, unknown category), or a cursor this API did not issue for this exact request — replayed from another endpoint, resource, metro or filter set, hand-crafted, or altered.

{
  "error": {
    "code": "bad_request",
    "message": "radius_m: must be at least 100",
    "details": {
      "param": "radius_m"
    },
    "request_id": "req_dfbc3295a8382b05"
  }
}

Missing, unknown or revoked X-API-Key.

{
  "error": {
    "code": "unauthorized",
    "message": "missing X-API-Key header",
    "request_id": "req_90e63908273f6bff"
  }
}

Two different reasons share this status.

{
  "error": {
    "code": "forbidden",
    "message": "key is not scoped to metro 'boston'",
    "details": {
      "metros": [
        "philadelphia"
      ]
    },
    "request_id": "req_9e7a750acef48ab2"
  }
}

No published, active resource with that id (or unknown metro).

{
  "error": {
    "code": "not_found",
    "message": "unknown metro 'boston'",
    "request_id": "req_7431b51e10ec2b77"
  }
}

The path exists; the method does not.

{
  "error": {
    "code": "method_not_allowed",
    "message": "POST is not allowed on this path; this API is read-only",
    "details": {
      "allow": [
        "GET",
        "HEAD",
        "OPTIONS"
      ]
    },
    "request_id": "req_01J9Z3"
  }
}

A limit was reached.

{
  "error": {
    "code": "rate_limited",
    "message": "3 requests per minute exceeded",
    "request_id": "req_06bfd3c2d5e8aa9f"
  }
}

A bug on our side.

{
  "error": {
    "code": "internal",
    "message": "internal error",
    "request_id": "req_01J9Z3"
  }
}

This endpoint or feature is not available and will not become available without a configuration change — for ?address=, this means no geocoder is configured.

{
  "error": {
    "code": "not_implemented",
    "message": "this endpoint is not enabled on this deployment; it is not a fault and retrying will not help",
    "request_id": "req_01J9Z3"
  }
}

A transient outage: a dependency could not be reached or did not answer in time.

{
  "error": {
    "code": "unavailable",
    "message": "the service is temporarily unable to serve this request; retry after the interval in Retry-After",
    "request_id": "req_01J9Z3"
  }
}