# List events

> Events, optionally filtered by sport, competition, type, title and status.

Source: https://docs.stxapp.io/api/rest/events/list-events/

Events, optionally filtered by sport, competition, type, title and status. Defaults to newest-inserted first.

```http
GET /api/v1/events
```

Send it with your own demo key: [Try it](/quick-start/?op=events_get#try-it).

:::tip[In the SDKs]
- TypeScript: [`STX.events()`](/sdks/typescript/reference/stx/#events)
- Python: [`STX.events()`](/sdks/python/reference/stx/#events)
- C#: [`STXEventService.GetEventInfosAsync()`](/sdks/csharp/reference/market-data/#stxeventservice)
:::

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `event_ids` | `query` | string | no | Comma-separated event UUIDs. |
| `sports` | `query` | string | no | Comma-separated sport names, e.g. `Baseball,Basketball`. Exact case-insensitive match. |
| `competitions` | `query` | string | no | Comma-separated competition codes, e.g. `MLB,NFL`. |
| `event_types` | `query` | string | no | Comma-separated event types, matched as a case-insensitive **substring**. |
| `title` | `query` | string | no | A single title fragment, matched as a case-insensitive substring. |
| `status` | `query` | `scheduled` \| `in_progress` \| `completed` \| `cancelled` | no | A single event status, lowercase. This filter takes one value, not a comma-separated list. These are *event* statuses, not the market statuses `/markets` takes. |
| `promoted` | `query` | boolean | no | Filter to promoted events. Unlike `trading` on `/markets`, an unrecognized value is **silently ignored** rather than rejected: the filter is dropped and every event is returned. |
| `sort_by[name]` | `query` | `start_time` | no | Only `start_time` is supported. Unlike `/markets`, an unrecognized value is **silently ignored** and the default newest-inserted-first ordering is used, so a response may not carry the order you asked for. |
| `sort_by[direction]` | `query` | `asc` \| `desc` | no | `asc` or `desc`, defaulting to descending. Only meaningful alongside `sort_by[name]`, and silently ignored if unrecognized. |
| `limit` | `query` | integer | no | Rows per page. Defaults to 100 and is silently clamped to 200; a larger value is not an error. |
| `cursor` | `query` | string | no | Cursor from the previous response. Omit for the first page. |

## Responses

| Status | Description | Schema |
|---|---|---|
| `200` | Success | object |
| `400` | A parameter was missing or invalid. | Error |
| `401` | Missing, malformed or unrecognized signature, or a timestamp outside the 30-second window. Body: {"error":"Missing or invalid API key credentials"} | Error |
| `403` | The account behind this key is not active, for example it is pending approval or suspended. Body: {"error":"Your account is suspended. Contact support."}, the message naming the account's status. | Error |

## Example

Request:

```bash
curl --request GET \
  --url 'https://demo.stxapp.io/api/v1/events' \
  --header 'X-STX-ACCESS-KEY: <key-id>' \
  --header 'X-STX-ACCESS-TIMESTAMP: <unix-ms>' \
  --header 'X-STX-ACCESS-SIGNATURE: <base64-ed25519>'
```

Response `200`:

```json
{
  "cursor": null,
  "events": [
    {
      "archived": null,
      "competition": null,
      "event_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "event_type": null,
      "participants": null,
      "promoted": null,
      "short_title": null,
      "sport": null,
      "start_time": 0,
      "start_time_iso": "2026-08-25T04:42:46.242093Z",
      "status": null,
      "symbol": null,
      "title": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
|---|---|---|
| `cursor` | string | Opaque cursor for the next page. Pass the value from the previous response; omit for the first page. `null` once there are no more pages. |
| `archived` | boolean | Whether this event is archived. |
| `competition` | string | The competition for this event |
| `event_id` | uuid | The event the market belongs to. |
| `event_type` | string | The type of this event, e.g. `ad_hoc`, `baseball_game`, `basketball_game`. |
| `participants` | array | The event's participants, as an array of `{name, role, short_name, abbreviation}`. |
| `promoted` | boolean | Whether this event is promoted. |
| `short_title` | string | The short title for this event |
| `sport` | string | The sport for this event |
| `start_time` | int64 | Start time of this event UNIX microseconds. |
| `start_time_iso` | date-time | Start time of this event |
| `status` | string | The status of this event |
| `symbol` | string | The STX symbol for this event |
| `title` | string | The title of this event |