# List place events

> Same as GET /v1/{metro}/events?place_id={id}, addressed by the place instead of the metro.

Source: https://api.tailend.dev/docs/api/list-place-events

```http
GET https://api.tailend.dev/v1/places/{id}/events
X-API-Key: $TAILEND_API_KEY
```

Same as `GET /v1/{metro}/events?place_id={id}`, addressed by the place instead of the metro.

Resolves the place by id, `404`s if it does not exist, takes the metro from the place's own row, and delegates to the ordinary events list — every other list parameter (paging, `fields=`, `include=`, date windows, `min_confidence`, ...) keeps working exactly as it does there. Same auth, metro scope, rate limiting and metering as the list endpoint; a key without access to the place's metro gets the same `403` the list endpoint gives.

Authorization: send your key in the `X-API-Key` header. Available on every plan.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes | Listing id. |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string (date) | no | Local calendar date (metro timezone), inclusive. |
| `to` | string (date) | no | Local calendar date (metro timezone), inclusive; at most 366 days after from. |
| `min_confidence` | number | no | Drop rows whose confidence is below this. |
| `category` | array of string | no | Keep rows whose categories contain any of these. |
| `audience` | array of string | no | Keep rows whose audience is one of these. |
| `season` | array of string | no | Events, classes and camps only. |
| `occasion` | string | no | Events and classes tagged for a seasonal occasion. |
| `team` | string | no | Events built around a local pro sports team (watch parties, game-day themed events, team or mascot appearances). |
| `age` | integer | no | A child's age in years. |
| `neighborhood` | string | no | Neighborhood slug or free-text name (case-insensitive). |
| `lat` | number | no | Center latitude for a radius search. |
| `lng` | number | no | Center longitude for a radius search. |
| `radius_m` | integer | no | Radius in metres around lat/lng (or near_zip, where enabled). |
| `zip` | array of string | no | Beta — may not be enabled for all keys yet. |
| `near_zip` | string | no | Beta — may not be enabled for all keys yet. |
| `include_approximate` | boolean | no | Beta — may not be enabled for all keys yet. |
| `free` | boolean | no | Events, classes, and camps only; ignored for places. |
| `has_time` | boolean | no | true keeps only events with a stated clock time. |
| `recurring` | boolean | no | Filter on is_recurring. |
| `indoor` | boolean | no | Filter on is_indoor, a fact about the linked place. |
| `outdoor` | boolean | no | Filter on is_outdoor, a fact about the linked place. |
| `sensory` | boolean | no | Filter on is_sensory_friendly (on events and classes, the linked place's; on places, the place's own). |
| `changed_since` | string (date-time) | no | Sync mode. |
| `q` | string | no | Full-text search over the listing's name and search text (websearch syntax: storytime park, "drop in", art -camp). |
| `weekday` | array of string | no | Keep rows on any of these local days. |
| `start_after` | string | no | Local start time at or after this, HH:MM (or HH:MM:SS). |
| `start_before` | string | no | Local start time strictly before this, HH:MM; 09:00–12:00 is the morning and 12:00 belongs to the afternoon. |
| `max_price` | number | no | A budget. |
| `organization_id` | string (uuid) | no | Keep rows published by this organization (organization.id). |
| `fields` | array of string | no | Keep only these dotted paths on each item (name,place.name,price.is_free); id and type are always kept so a trimmed item stays addressable. |
| `expand` | array of string | no | Attach the full Place and/or the Organization behind each item under expanded, one extra read per expansion per page (not per row). |
| `include` | array of string | no | Opt into a block the lean default response leaves out. |
| `include_mode` | string | no | How an include= the key is not entitled to is handled. |
| `cursor` | string | no | Opaque cursor from meta.next_cursor. |
| `page` | integer | no | 1-based page number (browse mode). |
| `facets` | array of string | no | Counts over every listing that matches the filters, not just this page, returned as a top-level facets object beside data and meta. |
| `limit` | integer | no | Items per page, 1 to 200. |

## Example request

```bash
curl -sS \
  -H "X-API-Key: $TAILEND_API_KEY" \
  "https://api.tailend.dev/v1/places/b81a95d2-1d4e-46fd-9cff-322a41e429ad/events"
```

## Responses

### 200

A page of events.

```json
{
  "data": [
    {
      "id": "b81a95d2-1d4e-46fd-9cff-322a41e429ad",
      "type": "event",
      "slug": "toddler-time-ages-5-and-under-toddler-time-observer-e50d61ea",
      "name": "Toddler Time (Ages 5 and Under) / Toddler Time Observer",
      "description": "Includes Treehouses and Free Play Areas for toddlers ages 5 and under.",
      "starts_local": "2026-09-14T09:30:00",
      "ends_local": null,
      "start_time": "09:30:00",
      "has_time": true,
      "has_date": true,
      "all_day": false,
      "timezone": "America/New_York",
      "starts_at": "2026-09-14T13:30:00.000Z",
      "ends_at": null,
      "is_recurring": true,
      "rrule": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR",
      "recurrence_description": null,
      "place": {
        "id": "9cde4494-6c2a-4bfc-b15a-22edce13f3f7",
        "slug": "treehouse-world-d34361f7",
        "name": "Treehouse World"
      },
      "location": {
        "address": "1442 Phoenixville Pike, West Chester, PA 19380, USA",
        "street_address": "1442 Phoenixville Pike, West Chester, PA 19380, USA",
        "city": "West Chester",
        "state": "PA",
        "zip": "19380",
        "lat": 40.0240296,
        "lng": -75.5858949,
        "neighborhood": "Newtown Square",
        "neighborhood_slug": "newtown-square"
      },
      "price": {
        "type": "fixed",
        "min": 12,
        "max": 12,
        "scope": "admission",
        "note": "$12.00",
        "unit": "per_session",
        "is_free": false,
        "currency": "USD"
      },
      "ages": {
        "min": 1,
        "max": 5,
        "text": null,
        "audience": "kids",
        "bands": [
          "baby",
          "toddler",
          "young_kids"
        ]
      },
      "audience": "kids",
      "traits": {
        "seasons": [
          "fall"
        ]
      },
      "categories": [
        "social_play_spaces"
      ],
      "occasions": [],
      "teams": [],
      "registration_url": "https://treehouseworld.com/pages/admission-prices",
      "ticket_url": null,
      "registration_required": false,
      "is_sold_out": false,
      "image_url": null,
      "organization": {
        "id": "c45b9b3a-45ab-4f9c-b2e2-986dcb921f25",
        "name": "Treehouse World",
        "slug": "treehouseworldcom-a86bfd79"
      },
      "confidence": 1,
      "verified_at": "2026-09-26T14:06:38.332Z",
      "metro": "philadelphia",
      "status": "published",
      "created_at": "2026-09-14T08:04:04.969Z",
      "updated_at": "2026-09-26T14:06:38.788Z",
      "links": {
        "self": "/v1/events/b81a95d2-1d4e-46fd-9cff-322a41e429ad",
        "place": "/v1/places/9cde4494-6c2a-4bfc-b15a-22edce13f3f7",
        "organization": "/v1/organizations/c45b9b3a-45ab-4f9c-b2e2-986dcb921f25"
      }
    }
  ],
  "meta": {
    "limit": 1,
    "count": 1,
    "has_more": false,
    "applied_filters": {
      "from": "2026-09-14",
      "to": "2026-10-14",
      "min_confidence": 0.7,
      "audience": [
        "not_adults"
      ]
    },
    "defaults_applied": [
      "from",
      "to",
      "min_confidence",
      "audience"
    ]
  }
}
```

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

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

### 401

Missing, unknown or revoked X-API-Key.

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

### 403

Two different reasons share this status.

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

### 404

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

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

### 405

The path exists; the method does not.

```json
{
  "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"
  }
}
```

### 429

A limit was reached.

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

### 500

A bug on our side.

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

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

```json
{
  "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"
  }
}
```

### 503

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

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