Skip to main content

Gigs API

List gigs​

Endpoint: GET /gigs

Headers:

  • X-F-Authorization: Client token (required)

Query parameters:

  • page, limit — Pagination (default limit 20, max 100).
  • artist — Optional artist id; returns that artist’s gigs only.
  • country — Optional; case-insensitive exact match on the linked festival’s country (same as GET /festivals).
  • Month filter (optional):
    • month=YYYY-MM — UTC calendar month (e.g. 2026-04).
    • or year=YYYY and month=M where M is 1–12.

When no month is set, the API returns upcoming gigs (same behavior as before): gig start_time in the future, or TBA gigs on festivals that are still active or upcoming.

When month is set, the API returns gigs whose effective time falls in that month (UTC):

  • If the gig has a start_time, it must fall inside the month.
  • If the gig has no start_time (TBA slot), the linked festival’s start_time must fall inside the month.

You can combine country with the default upcoming filter or with month.

Response:

{
  "gigs": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 0,
    "totalPages": 0,
    "hasMore": false
  }
}

Gigs chart​

Endpoint: GET /gigs/chart

Loads all upcoming gigs (same rules as GET /gigs without month), keeps rows with a non-null artist_id, counts how many gigs each artist has, then returns { artists: [ { artist, gig_count } ] } sorted by gig_count descending.

Query parameters:

  • limit (optional): Max artists returned (default 100, maximum 200).