Showings & availability

Scheduled performances, published prices and seat observations.

Production · organization access required

Requests require an active organization grant and an API key or Clerk session. Results respect your granted scopes and markets. Access details →

GET`/v1/showings`

Showings.

Parameters

Name	Type	Details
`limit`query · optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`query · optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`scope`query · optional	`string`	Defaults to current (D1-owned). Archived selects published history; all explicitly combines both. Ownership is independent of Showing or premiere dates. Archived/all requires history:read.Values: current, archived, all
`releaseId`query · optional	`string`	Public country Release identifier (crl_…).
`venueId`query · optional	`string`	Public venue identifier (ven_…).
`movieId`query · optional	`string`	Public canonical movie identifier (mov_…).
`operatorId`query · optional	`string`	Public operator identifier (opr_…).
`marketId`query · optional	`string`	Public market identifier (mkt_…).
`countryCode`query · optional	`string`	Optional two-letter country filter. This narrows results; it does not grant access.Pattern: ^[A-Za-z]{2}$
`localDate`query · optional	`string`	Cinema-local calendar date, YYYY-MM-DD. Cannot be combined with timestamp bounds.
`startsFrom`query · optional	`string`	Inclusive start timestamp. ISO 8601; offsets are normalized to UTC.
`startsBefore`query · optional	`string`	Exclusive end timestamp. The schedule window is limited to 31 days.

Shell · authenticated request

curl "https://api.boxobserver.com/v1/showings" \
  -H "Authorization: Bearer $BOX_OBSERVER_API_KEY"

Response

200 application/json · Success shape within your granted access.

Illustrative response shape · not live data

{
  "data": [],
  "page": {
    "nextCursor": null,
    "hasMore": false
  },
  "meta": {
    "requestId": "example-request-id",
    "generatedAt": "2026-09-04T12:00:00.000Z"
  }
}

Response fields

Field	Type and constraints
`data`Required	`array<object>`
`data[].id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].releaseId`Required	`string \| null`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].status`Required	`string`Values: scheduled, unlisted, cancelled
`data[].startsAt`Required	`string`Format: date-time
`data[].localDate`Required	`string`Format: date
`data[].timeZone`Required	`string`
`data[].venue`Required	`object`
`data[].venue.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].venue.name`Required	`string`
`data[].venue.programmingType`Required	`string`Values: mainstream, mixed, specialist
`data[].venue.market`Required	`object`
`data[].venue.market.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].venue.market.name`Required	`string`
`data[].venue.market.countryCode`Required	`string`
`data[].venue.market.timeZone`Required	`string`
`data[].auditorium`Required	`object \| null`
`data[].auditorium.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].auditorium.name`Required	`string`
`data[].auditorium.capacity`Required	`integer \| null`Minimum: 0
`data[].auditorium.experiences`Required	`array<string> \| null`
`data[].movie`Required	`object`
`data[].movie.canonicalMovie`Required	`object \| null`
`data[].movie.canonicalMovie.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].movie.canonicalMovie.title`Required	`string`
`data[].movie.canonicalMovie.originalTitle`Required	`string \| null`
`data[].movie.canonicalMovie.releaseYear`Required	`integer \| null`
`data[].movie.canonicalMovie.runtimeMinutes`Required	`integer \| null`Minimum: 0
`data[].movie.sourceTitle`Required	`string`
`data[].movie.sourceOriginalTitle`Required	`string \| null`
`data[].movie.identityStatus`Required	`string`Values: canonical, source
`data[].format`Required	`string`Values: 2d, 3d
`data[].experiences`Required	`array<string>`
`data[].experienceSource`Required	`string \| null`Values: showing, auditorium,
`data[].language`Required	`string \| null`
`data[].capacity`Required	`integer \| null`Minimum: 0
`data[].capacitySource`Required	`string \| null`Values: showing, observation, auditorium,
`data[].price`Required	`object`
`data[].price.status`Required	`string`Values: exact, derived, unavailable
`data[].price.amountMinor`Required	`integer \| null`Minimum: 0
`data[].price.currency`Required	`string \| null`
`data[].price.source`Required	`string \| null`Values: providerSchedule, providerBooking, officialTariff, legacyUnknown,
`data[].price.observedAt`Required	`string \| null`Format: date-time
`data[].price.lastConfirmedAt`Required	`string \| null`Format: date-time
`data[].price.options`Optional	`array<object>`Default: []
`data[].price.options[].offerKey`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].price.options[].label`Required	`string`
`data[].price.options[].amountMinor`Required	`integer`Minimum: 0
`data[].price.options[].currency`Required	`string`
`data[].price.options[].admissionsIncluded`Required	`integer`Minimum: 0
`data[].seatAvailability`Required	`object \| null`
`data[].seatAvailability.status`Required	`string`Values: exact, derived, unavailable
`data[].seatAvailability.observedAt`Required	`string`Format: date-time
`data[].seatAvailability.checkpoint`Required	`string`
`data[].seatAvailability.capacity`Required	`integer \| null`Minimum: 0
`data[].seatAvailability.availableSeats`Required	`integer \| null`Minimum: 0
`data[].seatAvailability.occupiedEstimate`Required	`integer \| null`Minimum: 0
`data[].seatAvailability.occupancyRatio`Required	`number \| null`Minimum: 0 · Maximum: 1
`data[].updatedAt`Required	`string`Format: date-time
`page`Required	`object`
`page.nextCursor`Required	`string \| null`
`page.hasMore`Required	`boolean`
`meta`Required	`object`
`meta.requestId`Required	`string`
`meta.generatedAt`Required	`string`Format: date-time

Errors: 400, 401, 403, 429, 500, 503. Response format and retry guidance →

GET`/v1/showings/{id}`

Showing.

Replace {id} with the appropriate public identifier returned by the API.

Parameters

Name	Type	Details
`id`path · required	`string`	Public resource identifier returned by the API.

Shell · authenticated request

curl "https://api.boxobserver.com/v1/showings/{id}" \
  -H "Authorization: Bearer $BOX_OBSERVER_API_KEY"

Response

200 application/json · Success shape within your granted access.

Illustrative response shape · not live data

{
  "data": {
    "id": "shw_ZXhhbXBsZQ",
    "releaseId": null,
    "status": "scheduled",
    "startsAt": "2026-09-04T12:00:00.000Z",
    "localDate": "2026-09-04",
    "timeZone": "Europe/Bucharest",
    "venue": {
      "id": "ven_ZXhhbXBsZQ",
      "name": "example",
      "programmingType": "mainstream",
      "market": {
        "id": "mkt_ZXhhbXBsZQ",
        "name": "example",
        "countryCode": "RO",
        "timeZone": "Europe/Bucharest"
      }
    },
    "auditorium": null,
    "movie": {
      "canonicalMovie": null,
      "sourceTitle": "example",
      "sourceOriginalTitle": null,
      "identityStatus": "source"
    },
    "format": "2d",
    "experiences": [],
    "experienceSource": null,
    "language": null,
    "capacity": null,
    "capacitySource": null,
    "price": {
      "status": "unavailable",
      "amountMinor": null,
      "currency": null,
      "source": null,
      "observedAt": null,
      "lastConfirmedAt": null,
      "options": []
    },
    "seatAvailability": null,
    "updatedAt": "2026-09-04T12:00:00.000Z"
  },
  "meta": {
    "requestId": "example-request-id",
    "generatedAt": "2026-09-04T12:00:00.000Z"
  }
}

Response fields

Field	Type and constraints
`data`Required	`object`
`data.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data.releaseId`Required	`string \| null`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data.status`Required	`string`Values: scheduled, unlisted, cancelled
`data.startsAt`Required	`string`Format: date-time
`data.localDate`Required	`string`Format: date
`data.timeZone`Required	`string`
`data.venue`Required	`object`
`data.venue.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data.venue.name`Required	`string`
`data.venue.programmingType`Required	`string`Values: mainstream, mixed, specialist
`data.venue.market`Required	`object`
`data.venue.market.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data.venue.market.name`Required	`string`
`data.venue.market.countryCode`Required	`string`
`data.venue.market.timeZone`Required	`string`
`data.auditorium`Required	`object \| null`
`data.auditorium.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data.auditorium.name`Required	`string`
`data.auditorium.capacity`Required	`integer \| null`Minimum: 0
`data.auditorium.experiences`Required	`array<string> \| null`
`data.movie`Required	`object`
`data.movie.canonicalMovie`Required	`object \| null`
`data.movie.canonicalMovie.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data.movie.canonicalMovie.title`Required	`string`
`data.movie.canonicalMovie.originalTitle`Required	`string \| null`
`data.movie.canonicalMovie.releaseYear`Required	`integer \| null`
`data.movie.canonicalMovie.runtimeMinutes`Required	`integer \| null`Minimum: 0
`data.movie.sourceTitle`Required	`string`
`data.movie.sourceOriginalTitle`Required	`string \| null`
`data.movie.identityStatus`Required	`string`Values: canonical, source
`data.format`Required	`string`Values: 2d, 3d
`data.experiences`Required	`array<string>`
`data.experienceSource`Required	`string \| null`Values: showing, auditorium,
`data.language`Required	`string \| null`
`data.capacity`Required	`integer \| null`Minimum: 0
`data.capacitySource`Required	`string \| null`Values: showing, observation, auditorium,
`data.price`Required	`object`
`data.price.status`Required	`string`Values: exact, derived, unavailable
`data.price.amountMinor`Required	`integer \| null`Minimum: 0
`data.price.currency`Required	`string \| null`
`data.price.source`Required	`string \| null`Values: providerSchedule, providerBooking, officialTariff, legacyUnknown,
`data.price.observedAt`Required	`string \| null`Format: date-time
`data.price.lastConfirmedAt`Required	`string \| null`Format: date-time
`data.price.options`Optional	`array<object>`Default: []
`data.price.options[].offerKey`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data.price.options[].label`Required	`string`
`data.price.options[].amountMinor`Required	`integer`Minimum: 0
`data.price.options[].currency`Required	`string`
`data.price.options[].admissionsIncluded`Required	`integer`Minimum: 0
`data.seatAvailability`Required	`object \| null`
`data.seatAvailability.status`Required	`string`Values: exact, derived, unavailable
`data.seatAvailability.observedAt`Required	`string`Format: date-time
`data.seatAvailability.checkpoint`Required	`string`
`data.seatAvailability.capacity`Required	`integer \| null`Minimum: 0
`data.seatAvailability.availableSeats`Required	`integer \| null`Minimum: 0
`data.seatAvailability.occupiedEstimate`Required	`integer \| null`Minimum: 0
`data.seatAvailability.occupancyRatio`Required	`number \| null`Minimum: 0 · Maximum: 1
`data.updatedAt`Required	`string`Format: date-time
`meta`Required	`object`
`meta.requestId`Required	`string`
`meta.generatedAt`Required	`string`Format: date-time

Errors: 400, 401, 403, 404, 429, 500, 503. Response format and retry guidance →

GET`/v1/showings/{id}/availability`

Showing availability history.

Replace {id} with the appropriate public identifier returned by the API.

Parameters

Name	Type	Details
`id`path · required	`string`	Public resource identifier returned by the API.
`limit`query · optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`query · optional	`string`	Opaque cursor from the previous response. Preserve the same filters.

Shell · authenticated request

curl "https://api.boxobserver.com/v1/showings/{id}/availability" \
  -H "Authorization: Bearer $BOX_OBSERVER_API_KEY"

Response

200 application/json · Success shape within your granted access.

Illustrative response shape · not live data

{
  "data": [],
  "page": {
    "nextCursor": null,
    "hasMore": false
  },
  "meta": {
    "requestId": "example-request-id",
    "generatedAt": "2026-09-04T12:00:00.000Z"
  }
}

Response fields

Field	Type and constraints
`data`Required	`array<object \| null>`
`data[].plannedAt`Required	`string`Format: date-time
`data[].scheduledStartAt`Required	`string`Format: date-time
`page`Required	`object`
`page.nextCursor`Required	`string \| null`
`page.hasMore`Required	`boolean`
`meta`Required	`object`
`meta.requestId`Required	`string`
`meta.generatedAt`Required	`string`Format: date-time

Errors: 400, 401, 403, 429, 500, 503. Response format and retry guidance →

Showings & availability

GET/v1/showings

Parameters

Response

GET/v1/showings/{id}

Parameters

Response

GET/v1/showings/{id}/availability

Parameters

Response

GET`/v1/showings`

GET`/v1/showings/{id}`

GET`/v1/showings/{id}/availability`