Docs / Event Data API / Endpoints / List events

List events

Returns events by start time, soonest first. Every timestamp is an RFC 3339 instant in UTC — render it in the venue's own timezone, which for every source live today is Asia/Baku (UTC+4).

GET https://api.softon.dev/v1/events Copy

Query parameters

Parameter	Type	Description
`q`	string	Full-text match on name, venue and description.
`category`	string	Category slug.
`starts_after`	timestamp	Events starting at or after this instant.
`starts_before`	timestamp	Events starting at or before this instant.
`limit`	integer	Items per page, 1–100. Defaults to 25.
`cursor`	string	Opaque cursor from a previous response's meta.next. Do not construct one.
`order`	string	Sort field, prefixed with - to reverse.
`source`	string	Restrict to one scraper source.

Request

curl -G https://api.softon.dev/v1/events \
  -H "Authorization: Bearer $SOFTON_KEY" \
  -d q=gimnastika -d category=exhibitions -d limit=50

req, _ := http.NewRequestWithContext(ctx, "GET",
    "https://api.softon.dev/v1/events", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SOFTON_KEY"))

q := req.URL.Query()
q.Set("q", "gimnastika")
q.Set("category", "exhibitions")
q.Set("limit", "50")
req.URL.RawQuery = q.Encode()

res, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer res.Body.Close()

var page struct {
    Data []Event `json:"data"`
    Meta struct{ Next *string `json:"next"` } `json:"meta"`
}
if err := json.NewDecoder(res.Body).Decode(&page); err != nil { log.Fatal(err) }
// page.Meta.Next → send it back as ?cursor= for the following page

import json, os, urllib.parse, urllib.request

url = "https://api.softon.dev/v1/events" + "?" + urllib.parse.urlencode({
    "q": "gimnastika",
    "category": "exhibitions",
    "limit": "50",
})
req = urllib.request.Request(url, headers={
    "Authorization": "Bearer " + os.environ["SOFTON_KEY"],
})
page = json.load(urllib.request.urlopen(req))
# page["meta"]["next"] → send it back as ?cursor= for the following page

const url = new URL("https://api.softon.dev/v1/events");
url.searchParams.set("q", "gimnastika");
url.searchParams.set("category", "exhibitions");
url.searchParams.set("limit", "50");

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.SOFTON_KEY}` },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const { data, meta } = await res.json();
// meta.next → send it back as ?cursor= for the following page

Response

The envelope is identical on every softon.dev API: data, meta, error. Only the shape inside data changes per dataset — see the response envelope.

{
  "data": [
    {
      "id": "iticket:12299",
      "source": "iticket",
      "name": "The Golden Collection: Pearls of Azerbaijani Fine Art",
      "category": "exhibitions",
      "venue": {
        "id": "museum-center", "name": "Museum Center",
        "address": null, "lat": 40.3698087, "lng": 49.8425258
      },
      "starts_at": "2026-08-05T06:00:00Z",
      "ends_at": "2026-09-15T13:00:00Z",
      "price": { "min": 7, "max": 10, "currency": "AZN" },
      "age_limit": "16+",
      "tickets_available": 7199,
      "url": "https://iticket.az/az/events/exhibitions/the-golden-collection-pearls-of-azerbaijani-fine-art8749",
      "external_url": null,
      "ingested_at": "2026-08-04T23:55:46.834186Z"
    }
  ],
  "meta": { "count": 1, "next": "eyJvIjoyfQ", "request_id": "req_9Fv3" },
  "error": null
}

Fields of each item in `data[]`

Field	Type	Description
`id`	string	Stable identifier, "<source>:<source id>".
`source`	string	Which scraper produced this event.
`name`	string	Event name as published.
`category`	string · nullable	Category slug: concerts, theatre, exhibitions, sport, cinema.
`venue`	object · nullable	id, name, address, lat, lng. Coordinates where the source geocodes.
`starts_at`	timestamp · nullable	Start time as an RFC 3339 instant in UTC. Convert with the venue's timezone for display — all current venues are Asia/Baku (UTC+4).
`ends_at`	timestamp · nullable	End time in UTC, when the source publishes one.
`price`	object · nullable	min, max and currency across ticket tiers.
`age_limit`	string · nullable	Age restriction as published, e.g. "16+".
`tickets_available`	integer · nullable	Live inventory. null where the source does not expose it — never 0 as a stand-in.
`description`	string · nullable	Editorial copy for the event.
`url`	string · nullable	Canonical page on the source site.
`external_url`	string · nullable	Information or ticketing page. NOT guaranteed to be a purchase link — cinema sources have no dereferenceable buy href.
`poster_url`	string · nullable	Artwork, highest resolution the source offers.
`sessions`	array · nullable	Every individual showing, each with its own price range and inventory. Present on a detail fetch.
`ingested_at`	timestamp	When this version was stored.

Try it

Send the request to see a response.