> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akaramarkets.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upcoming games

> Scheduled games your account has been granted ahead of any session

## Endpoint

```
GET /api/upcoming
```

Top-level, like the [sessions catalog](/api-reference/catalog). The rows are **scheduled games**,
not sessions — access can be granted on a game before any feed exists for it, and this endpoint is
where those grants surface: your schedule of covered games, soonest first. There is nothing to
subscribe to yet; when coverage goes live, the session appears in `GET /api/sessions` carrying the
same `gameId`, and every feed URL comes from that session row.

A game leaves this list when its scheduled window has fully passed, whether or not a session ever
covered it.

### Authentication

Same as the sessions catalog: a valid `ss_` API key or JWT as a Bearer token or `?token=`, no
anonymous tier. The list is exactly the games *your* account was granted — there is no public
slice here.

### Error responses

| Status | Condition                |
| ------ | ------------------------ |
| `401`  | Missing or invalid token |

***

## Response

```json theme={null}
{
  "games": [
    {
      "gameId": "5f0c9d0e-3c14-4c6e-9d38-7a4f0a1b2c3d",
      "league": "wnba",
      "sport": "basketball",
      "matchup": { "a": "Dallas Wings", "b": "Connecticut Sun" },
      "summary": "Connecticut Sun @ Dallas Wings",
      "scheduledStart": "2026-08-02T23:00:00+00:00"
    }
  ]
}
```

| Field            | Type           | Description                                                                                                                                                                                          |
| ---------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gameId`         | string         | The scheduled game's id. The join key against the sessions catalog: sessions covering this game carry the same value as their `gameId`, so replace this row with the session row(s) once they appear |
| `league`         | string         | League slug — same vocabulary as the [sessions catalog](/api-reference/catalog#league-slugs)                                                                                                         |
| `sport`          | string         | Which event vocabulary and state shape the eventual feed will speak — same values as the catalog's `sport`                                                                                           |
| `matchup`        | object         | The side display names `{ a, b }` (home, away). Either side is `null` for a manually-entered game without team fields — fall back to `summary`                                                       |
| `summary`        | string \| null | A human-readable game label, when one exists                                                                                                                                                         |
| `scheduledStart` | string         | ISO-8601 scheduled start time. A promise from the schedule, not a session stamp — the session's own `startedAt` is when coverage actually began                                                      |

**Ordering** is soonest first (`scheduledStart` ascending).

### Polling pattern

Poll this beside `GET /api/sessions?status=open` and key both by `gameId`: a game in this list with
no matching open session is *scheduled*; once an open session shares its `gameId`, that session row
is the live one (subscribe with its `sessionId`), and this list drops the game shortly after its
window passes.