# Concerts and schedules

Find film-music concerts and explore their scheduled performances. A concert is the named program; its events are individual dates and locations. These endpoints describe live events, not a catalog of concert-film releases.

## Find upcoming programs

```sh
curl --get "$ATM_API_BASE_URL/concerts" \
  --header "Authorization: Bearer $ATM_API_KEY" \
  --data-urlencode 'upcoming=true' \
  --data-urlencode 'sort=next_date' \
  --data-urlencode 'limit=10'
```

Use `q` to match part of a concert title. `country` and `city` match complete location values. Country values can be names or codes; reuse the value from an event response rather than assuming one universal code system.

`date_from` and `date_to` define an inclusive date range. With `upcoming=true`, events are restricted to dates from today in UTC onward. Each result includes `next_date` and `upcoming_event_count` for matching upcoming dates. A `null` next date means none is available.

## Read a schedule

Set `ATM_CONCERT_ID` to an ID or slug returned by the search:

```sh
curl --get "$ATM_API_BASE_URL/concerts/$ATM_CONCERT_ID" \
  --header "Authorization: Bearer $ATM_API_KEY" \
  --data-urlencode 'limit=20'
```

Concert details include a paginated schedule at `data.events`. To continue it, send `data.events.pagination.next_cursor` as `cursor` to the same detail endpoint. Keep the same date and location filters.

The detail endpoint accepts `date_from`, `date_to`, `country`, and `city`. To restrict the schedule to future dates, supply `date_from` explicitly; `upcoming` is a search parameter only.

## Display event information

Each event contains a local calendar `date`, `country`, `city`, and optional `ticket_url`, `additional_url`, and `source_url` values.

A date does not include a performance start time or time zone. Display it as a calendar date rather than converting it as a UTC timestamp. Ticket links do not report current seat availability or prices; direct users to the linked provider for booking details.

**Next:** [Paginating nested lists →](/pagination#nested-lists)