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

# Public event info

> Read upcoming public Broadcast events through api.broadcast.events.

export const SourceFieldsTable = () => <table>
        <thead>
            <tr>
                <th>Field</th>
                <th>Type</th>
                <th>Description</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>
                    <code>provider</code>
                </td>
                <td>String</td>
                <td>Current source provider. At the moment this is internal</td>
            </tr>
        </tbody>
    </table>;

export const LinksFieldsTable = ({includeWorkspaceFields = false}) => {
  const rows = [[<code>self</code>, 'String', 'Public Broadcast URL for the event']];
  if (includeWorkspaceFields) {
    rows.push([<code>moreInfo</code>, 'String', 'Optional external information URL']);
  }
  return <table>
            <thead>
                <tr>
                    <th>Field</th>
                    <th>Type</th>
                    <th>Description</th>
                </tr>
            </thead>
            <tbody>
                {rows.map((row, index) => <tr key={index}>
                        {row.map((cell, cellIndex) => <td key={cellIndex}>{cell}</td>)}
                    </tr>)}
            </tbody>
        </table>;
};

export const ImageVariantsFieldsTable = () => <table>
        <thead>
            <tr>
                <th>Field</th>
                <th>Type</th>
                <th>Description</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>
                    <code>micro</code>
                </td>
                <td>String</td>
                <td>Small preview variant</td>
            </tr>
            <tr>
                <td>
                    <code>small</code>
                </td>
                <td>String</td>
                <td>Small image variant</td>
            </tr>
            <tr>
                <td>
                    <code>medium</code>
                </td>
                <td>String</td>
                <td>Medium image variant</td>
            </tr>
            <tr>
                <td>
                    <code>large</code>
                </td>
                <td>String</td>
                <td>Large image variant</td>
            </tr>
        </tbody>
    </table>;

export const ImageAssetFieldsTable = () => <table>
        <thead>
            <tr>
                <th>Field</th>
                <th>Type</th>
                <th>Description</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>
                    <code>alt</code>
                </td>
                <td>String</td>
                <td>Alt text when available</td>
            </tr>
            <tr>
                <td>
                    <code>url</code>
                </td>
                <td>String</td>
                <td>Default image URL</td>
            </tr>
            <tr>
                <td>
                    <code>variants</code>
                </td>
                <td>Object</td>
                <td>Responsive image URLs in multiple sizes</td>
            </tr>
        </tbody>
    </table>;

export const MediaAndImagesFieldsTable = () => <table>
        <thead>
            <tr>
                <th>Field</th>
                <th>Type</th>
                <th>Description</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>
                    <code>media.image</code>
                </td>
                <td>Object</td>
                <td>Event image asset</td>
            </tr>
            <tr>
                <td>
                    <code>location.venue.media.image</code>
                </td>
                <td>Object</td>
                <td>Venue image asset</td>
            </tr>
        </tbody>
    </table>;

export const VenueProfileFieldsTable = () => <table>
        <thead>
            <tr>
                <th>Field</th>
                <th>Type</th>
                <th>Description</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>
                    <code>handle</code>
                </td>
                <td>String</td>
                <td>Profile handle such as @john-dee</td>
            </tr>
            <tr>
                <td>
                    <code>canonicalUrl</code>
                </td>
                <td>String</td>
                <td>Canonical public profile URL</td>
            </tr>
        </tbody>
    </table>;

export const VenueLinksFieldsTable = ({includeProfileFields = false}) => {
  const rows = [[<code>self</code>, 'String', 'Public Broadcast URL for the venue']];
  if (includeProfileFields) {
    rows.push([<code>entity</code>, 'String', 'Public entity route. Currently same as self'], [<code>profile</code>, 'String', 'Canonical profile URL when the venue has a slug']);
  }
  return <table>
            <thead>
                <tr>
                    <th>Field</th>
                    <th>Type</th>
                    <th>Description</th>
                </tr>
            </thead>
            <tbody>
                {rows.map((row, index) => <tr key={index}>
                        {row.map((cell, cellIndex) => <td key={cellIndex}>{cell}</td>)}
                    </tr>)}
            </tbody>
        </table>;
};

export const VenueGeoFieldsTable = () => <table>
        <thead>
            <tr>
                <th>Field</th>
                <th>Type</th>
                <th>Description</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>
                    <code>latitude</code>
                </td>
                <td>Number</td>
                <td>Venue latitude</td>
            </tr>
            <tr>
                <td>
                    <code>longitude</code>
                </td>
                <td>Number</td>
                <td>Venue longitude</td>
            </tr>
        </tbody>
    </table>;

export const VenueAddressFieldsTable = () => <table>
        <thead>
            <tr>
                <th>Field</th>
                <th>Type</th>
                <th>Description</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>
                    <code>street</code>
                </td>
                <td>String</td>
                <td>Street address</td>
            </tr>
            <tr>
                <td>
                    <code>city</code>
                </td>
                <td>String</td>
                <td>City name</td>
            </tr>
            <tr>
                <td>
                    <code>postalCode</code>
                </td>
                <td>String</td>
                <td>Postal or ZIP code</td>
            </tr>
            <tr>
                <td>
                    <code>country</code>
                </td>
                <td>String</td>
                <td>Two-letter country code such as NO</td>
            </tr>
        </tbody>
    </table>;

export const VenueFieldsTable = ({includeProfileFields = false}) => {
  const rows = [[<code>id</code>, 'String', 'Broadcast venue ID'], [<code>type</code>, 'String', 'Always venue'], [<code>name</code>, 'String', 'Venue name'], [<code>address</code>, 'Object', 'Venue address details'], [<code>geo</code>, 'Object', 'Venue coordinates when available'], [<code>links</code>, 'Object', includeProfileFields ? 'Public venue and profile links' : 'Public venue links']];
  if (includeProfileFields) {
    rows.push([<code>profile</code>, 'Object', 'Minimal profile metadata']);
  }
  rows.push([<code>media</code>, 'Object', 'Venue media assets']);
  return <table>
            <thead>
                <tr>
                    <th>Field</th>
                    <th>Type</th>
                    <th>Description</th>
                </tr>
            </thead>
            <tbody>
                {rows.map((row, index) => <tr key={index}>
                        {row.map((cell, cellIndex) => <td key={cellIndex}>{cell}</td>)}
                    </tr>)}
            </tbody>
        </table>;
};

export const LocationFieldsTable = () => <table>
        <thead>
            <tr>
                <th>Field</th>
                <th>Type</th>
                <th>Description</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>
                    <code>type</code>
                </td>
                <td>String</td>
                <td>One of venue, online, hybrid, or tba</td>
            </tr>
            <tr>
                <td>
                    <code>venue</code>
                </td>
                <td>Object</td>
                <td>Venue details when the event is tied to a venue</td>
            </tr>
        </tbody>
    </table>;

export const AttendancePriceFieldsTable = () => <table>
        <thead>
            <tr>
                <th>Field</th>
                <th>Type</th>
                <th>Description</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>
                    <code>text</code>
                </td>
                <td>String</td>
                <td>
                    Human-readable price label such as NOK 250 or Free Entry
                </td>
            </tr>
        </tbody>
    </table>;

export const AttendanceFieldsTable = ({includeWorkspaceFields = false}) => {
  const rows = [[<code>isFree</code>, 'Boolean', 'true when the event has free entry'], [<code>soldOut</code>, 'Boolean', 'true when the event is sold out'], [<code>price</code>, 'Object', 'Price details']];
  if (includeWorkspaceFields) {
    rows.push([<code>ticketing</code>, 'String', 'Primary ticket URL'], [<code>commonTicketUrl</code>, 'String', 'Shared or default ticket URL when available'], [<code>additionalPriceInfo</code>, 'String', 'Free-text pricing notes'], [<code>callToAction</code>, 'Object', 'Optional booking, reservation, or other CTA']);
  }
  return <table>
            <thead>
                <tr>
                    <th>Field</th>
                    <th>Type</th>
                    <th>Description</th>
                </tr>
            </thead>
            <tbody>
                {rows.map((row, index) => <tr key={index}>
                        {row.map((cell, cellIndex) => <td key={cellIndex}>{cell}</td>)}
                    </tr>)}
            </tbody>
        </table>;
};

export const ClassificationFieldsTable = ({includeWorkspaceFields = false}) => {
  const rows = [[<code>tags</code>, 'Array of strings', 'Event tags normalized for API output'], [<code>categories</code>, 'Array of strings', 'Event category list. Usually derived from the event type'], [<code>ageRestrictionText</code>, 'String', 'Age restriction label such as 18+'], [<code>isAllAges</code>, 'Boolean', 'true when the event is marked as all ages']];
  if (includeWorkspaceFields) {
    rows.push([<code>noAgeLimit</code>, 'Boolean', 'Raw workspace-facing flag for the same age concept']);
  }
  return <table>
            <thead>
                <tr>
                    <th>Field</th>
                    <th>Type</th>
                    <th>Description</th>
                </tr>
            </thead>
            <tbody>
                {rows.map((row, index) => <tr key={index}>
                        {row.map((cell, cellIndex) => <td key={cellIndex}>{cell}</td>)}
                    </tr>)}
            </tbody>
        </table>;
};

export const TimingFieldsTable = () => <table>
        <thead>
            <tr>
                <th>Field</th>
                <th>Type</th>
                <th>Description</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>
                    <code>doors</code>
                </td>
                <td>String</td>
                <td>Main event datetime in ISO format</td>
            </tr>
            <tr>
                <td>
                    <code>close</code>
                </td>
                <td>String</td>
                <td>End time in ISO format when available</td>
            </tr>
            <tr>
                <td>
                    <code>timezone</code>
                </td>
                <td>String</td>
                <td>Time zone for the event. Currently Europe/Oslo</td>
            </tr>
            <tr>
                <td>
                    <code>startTime</code>
                </td>
                <td>String</td>
                <td>Show start time in ISO format when available</td>
            </tr>
        </tbody>
    </table>;

export const EventObjectFieldsTable = ({includeWorkspaceFields = false}) => {
  const rows = [[<code>id</code>, 'String', 'Broadcast event ID'], [<code>type</code>, 'String', 'Always event'], [<code>title</code>, 'String', 'Primary event title']];
  if (includeWorkspaceFields) {
    rows.push([<code>descriptionMD</code>, 'String', 'Long-form event description']);
  }
  rows.push([<code>subtitle</code>, 'String', 'Secondary title when available'], [<code>summary</code>, 'String', 'Short event summary or blurb'], [<code>status</code>, 'String', 'Event status such as scheduled, cancelled, or sold_out'], [<code>timing</code>, 'Object', 'Event timing details'], [<code>classification</code>, 'Object', 'Tags, categories, and age guidance'], [<code>attendance</code>, 'Object', includeWorkspaceFields ? 'Price and workspace-specific ticketing fields' : 'Free, sold out, and price information'], [<code>location</code>, 'Object', 'Venue or online location details'], [<code>media</code>, 'Object', includeWorkspaceFields ? 'Event image plus optional embed/video metadata' : 'Event media assets'], [<code>links</code>, 'Object', includeWorkspaceFields ? 'Broadcast links and optional external info links' : 'Public Broadcast links']);
  if (includeWorkspaceFields) {
    rows.push([<code>meta</code>, 'Object', 'Workspace/internal event metadata'], [<code>relatedEvents</code>, 'Array', 'Related event references when available']);
  }
  rows.push([<code>source</code>, 'Object', 'Source metadata'], [<code>createdAt</code>, 'String', 'Event created timestamp in ISO format'], [<code>updatedAt</code>, 'String', 'Event updated timestamp in ISO format']);
  if (includeWorkspaceFields) {
    rows.push([<code>structuredData</code>, 'Object', 'Structured data payloads']);
  }
  return <table>
            <thead>
                <tr>
                    <th>Field</th>
                    <th>Type</th>
                    <th>Description</th>
                </tr>
            </thead>
            <tbody>
                {rows.map((row, index) => <tr key={index}>
                        {row.map((cell, cellIndex) => <td key={cellIndex}>{cell}</td>)}
                    </tr>)}
            </tbody>
        </table>;
};

## Overview

Use this endpoint to read upcoming public events from Broadcast.

* Endpoint: `GET https://api.broadcast.events/public/events`
* Auth: `Authorization: Bearer <api-key>`

The feed returns published, non-cancelled upcoming events and sorts results by start time.

For a history of API and documentation changes, see the [API changelog](/api-changelog).

## Approach

We intentionally keep this endpoint **simple**: it is a **heavily cached** feed that returns **a larger slice of events per request** (see `limit` below) instead of offering rich querying and server-side filtering.

That makes it a good fit for **prototyping and experiments**: pull a batch of data, then **filter, sort, and search in your own code or database**. Only light parameters (`limit` and optional `region`) are supported on the API.

**Source of truth:** Event details can change after you fetch them. We recommend linking end users to the **canonical event on Broadcast** using `links.self` (and venue pages when relevant) so people always see the latest information.

## Caching and plans

Responses are **cached on our side** to keep the feed fast and affordable.

| Tier     | Typical cache lifetime | Notes                                      |
| -------- | ---------------------- | ------------------------------------------ |
| Free     | About **5 minutes**    | Best for experiments and low-frequency use |
| Paid     | **Much shorter**       | Fresher data for production-style use      |
| Realtime | On request             | Contact us; **pricing is not fixed yet**   |

Exact TTLs can depend on your agreement—email [support@broadcast.events](mailto:support@broadcast.events) if you need a specific freshness target.

## Access and pricing

<Info>
  This API is currently available on request. Contact
  [support@broadcast.events](mailto:support@broadcast.events) to enable access
  for your workspace. We currently offer both free and paid options depending
  on your use case and volume.
</Info>

## Query parameters

| Name     | Type   | Required | Description                                                    |
| -------- | ------ | -------- | -------------------------------------------------------------- |
| `limit`  | Number | No       | Number of events to return. Default is `50`. Maximum is `250`. |
| `region` | String | No       | Filter events by venue region. Example: `Oslo`.                |

Only `limit` and `region` are supported. Any other query parameter returns a `400` response.

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.broadcast.events/public/events?limit=25&region=Oslo" \
    --header "Authorization: Bearer YOUR_API_KEY"
  ```

  ```http Raw HTTP theme={null}
  GET /public/events?limit=25&region=Oslo HTTP/1.1
  Host: api.broadcast.events
  Authorization: Bearer YOUR_API_KEY
  ```
</CodeGroup>

## Example response

Use the copy control on the code block to grab the full JSON.

```json title="Example response" lines wrap theme={null}
{
    "data": [
        {
            "id": "evt_123",
            "type": "event",
            "title": "Broadcast Showcase",
            "subtitle": "Live in Oslo",
            "summary": "An evening of live music and DJs.",
            "status": "scheduled",
            "timing": {
                "doors": "2026-04-10T18:00:00.000Z",
                "close": "2026-04-10T22:30:00.000Z",
                "timezone": "Europe/Oslo",
                "startTime": "2026-04-10T19:00:00.000Z"
            },
            "classification": {
                "tags": ["live", "indie"],
                "categories": ["concert"],
                "ageRestrictionText": "18+"
            },
            "attendance": {
                "isFree": false,
                "soldOut": false,
                "price": {
                    "text": "NOK 250"
                }
            },
            "location": {
                "type": "venue",
                "venue": {
                    "id": "venue_123",
                    "type": "venue",
                    "name": "John Dee",
                    "address": {
                        "city": "Oslo",
                        "country": "NO"
                    },
                    "links": {
                        "self": "https://www.broadcast.events/v/venue_123"
                    }
                }
            },
            "media": {
                "image": {
                    "url": "https://img.broadcastapp.no/example/tr:w-375",
                    "variants": {
                        "micro": "https://img.broadcastapp.no/example/tr:w-100",
                        "small": "https://img.broadcastapp.no/example/tr:w-178",
                        "medium": "https://img.broadcastapp.no/example/tr:w-375",
                        "large": "https://img.broadcastapp.no/example/tr:w-750"
                    }
                }
            },
            "links": {
                "self": "https://www.broadcast.events/events/broadcast-showcase/evt_123"
            },
            "source": {
                "provider": "internal"
            },
            "createdAt": "2026-03-01T12:00:00.000Z",
            "updatedAt": "2026-03-05T09:30:00.000Z"
        }
    ],
    "meta": {
        "count": 1,
        "itemCount": 1,
        "generatedAt": "2026-03-20T10:00:00.000Z",
        "limit": 25,
        "region": "Oslo"
    }
}
```

## Response fields

Empty values are omitted from the response, so some optional fields may be missing.

### At a glance

| Field  | Type   | Description                    |
| ------ | ------ | ------------------------------ |
| `data` | Array  | List of matching public events |
| `meta` | Object | Metadata about the response    |

### `meta`

| Field         | Type             | Description                                               |
| ------------- | ---------------- | --------------------------------------------------------- |
| `count`       | Number           | Number of events returned in this response                |
| `itemCount`   | Number           | Same as `count`. Included for consistency with other APIs |
| `generatedAt` | String           | ISO timestamp for when the response payload was generated |
| `limit`       | Number           | Effective limit used for the request                      |
| `region`      | String or `null` | Region filter applied to the request                      |

### Event object

<EventObjectFieldsTable />

### `timing`

<TimingFieldsTable />

### `classification`

<ClassificationFieldsTable />

### `attendance`

<AttendanceFieldsTable />

#### `attendance.price`

<AttendancePriceFieldsTable />

### `location`

<LocationFieldsTable />

#### `location.venue`

<VenueFieldsTable includeProfileFields={true} />

#### `location.venue.address`

<VenueAddressFieldsTable />

#### `location.venue.geo`

<VenueGeoFieldsTable />

#### `location.venue.links`

<VenueLinksFieldsTable includeProfileFields={true} />

#### `location.venue.profile`

<VenueProfileFieldsTable />

### Media and images

<MediaAndImagesFieldsTable />

#### Image asset

<ImageAssetFieldsTable />

#### `image.variants`

<ImageVariantsFieldsTable />

### Links and source

<LinksFieldsTable />

### `source`

<SourceFieldsTable />

## Error responses

| Status | Meaning                                                                            |
| ------ | ---------------------------------------------------------------------------------- |
| `400`  | Invalid query parameters, duplicate query parameters, or an invalid `region` value |
| `401`  | Missing, invalid, or expired API key                                               |
| `403`  | API key does not include the required scope                                        |
| `429`  | Too many requests                                                                  |
| `500`  | Internal server error                                                              |