BillyDocumentation

List events

Retrieves a paginated list of events belonging to your Billy organization. Each item carries flat session summary fields; use GET /v1/events/{event_id}/sessions to enumerate the sessions of an event.

Preview release

You are reading this operation as it behaves on the preview release target. It is also part of a released version — switch above for the copy you can depend on. Preview has no stability promise: its routes and payloads can change without notice, so pin a dated release before you depend on one.
GET
/v1/events

Retrieves a paginated list of events belonging to your Billy organization. Each item carries flat session summary fields; use GET /v1/events/{event_id}/sessions to enumerate the sessions of an event.

Authorization

HTTPBearer
AuthorizationBearer <token>

API key authentication. Format: Bearer billy:o:<organization_id>:<api_key>

Example: Bearer billy:o:yyyyyyyyyyyyyyyy:xxxxxxxxxxxxxxxxx

In: header

Query Parameters

page?Page

Page index (1-based, e.g., 1 for first page, 2 for second page)

Range1 <= value
Default1
perPage?|

Maximum number of records to return

startAt.gte?|

Return results where startAt is at or after this value. For datetime fields, use ISO 8601 format with timezone offset (e.g. 2026-03-01T00:00:00+02:00).

startAt.lte?|

Return results where startAt is at or before this value. For datetime fields, use ISO 8601 format with timezone offset (e.g. 2026-03-01T00:00:00+02:00).

tags?|

Filter by tag (comma separated, max 10). Returns events linked to any of the given tags (e.g. tags=rap music,jazz). Matching is case- and whitespace-insensitive (accents are kept) and scoped to your organization's tags.

Header Parameters

Billy-API-Version*string

Requested API version. Current context: preview.

Default"preview"

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/events" \  -H "Billy-API-Version: preview"
{  "items": [    {      "id": "evt_64f1c2a9e8b4a12f9c0a1234",      "createdAt": "2025-01-15T10:42:31.000Z",      "updatedAt": "2025-01-20T09:12:05.000Z",      "title": "Electro Night Festival",      "description": "An immersive electronic music experience with top international DJs.",      "imageUrl": "https://cdn.example.com/events/electro-night/banner.jpg",      "venueName": "La Grande Halle",      "venueAddress": {        "addressLine1": "211 Avenue Jean Jaurès",        "addressLine2": null,        "city": "Paris",        "postalCode": "75019",        "countryCode": "FR"      },      "eventTimezone": "Europe/Paris",      "currency": "EUR",      "sessionCount": 1,      "firstSessionStartAt": "2025-03-21T19:30:00+01:00",      "lastSessionStartAt": "2025-03-21T19:30:00+01:00",      "nextSessionStartAt": null,      "nextSessionId": null,      "tags": [        "concert",        "electro"      ]    }  ],  "page": 1,  "perPage": 10,  "totalPages": 1}