# List competitions

`GET /v1/competitions`

Competitions the caller's `entities` grant admits, with their seasons: a grant
naming competitions lists those only. Stable order: `name` ascending, then `id`
ascending; competitions without a current dated name (`name` null,
`name_status: unavailable`) follow, by `id`. `known_at` is not supported.

Parameters:
- `association_code` (query, string, optional): FIFA member-association code of national competitions (`ENG`, `SCO`, `ITA`). Confederation and FIFA competitions have no association code and are not matched by this filter.
- `cursor` (query, string, optional): Opaque page cursor from a previous `page.next_cursor`; filters must be repeated unchanged.
- `limit` (query, integer, optional): Maximum items per page.

Returns `200`: One page of competitions.
- `items` (array of objects):  See [the competition object](obj-Competition.md).
- `page` (object)
  - `next_cursor` (string, nullable): Cursor for the next page, or `null` on the last page.
  - `limit` (integer)

Errors: `400` Malformed parameter or cursor (`invalid-request`).; `401` Missing or invalid credential (`unauthenticated`).; `403` Operation not permitted (`forbidden`) or restricted by grants/rights (`not-entitled`).; `422` Well-formed but unanswerable (`invalid-range`, `unsupported-historical-capability`).; `429` The per-minute rate limit is used up (`rate-limited`) or a daily allowance is exhausted (`quota-exceeded`). Failed requests (403, 404, other 4xx, 5xx) use up the per-minute rate limit too.; `500` Unexpected failure (`internal-error`); `request_id` identifies the server-side record.; `503` A service this operation depends on, or the access check, is temporarily unavailable (`unavailable`, `policy-unavailable`).

Example request (200 · Default):

```bash
curl -G https://api.example.com/v1/competitions \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d limit=50 \
  -d association_code=SYN
```

Example response (200):

```json
{
  "items": [
    {
      "id": "cmp_1",
      "name": "Synthetic Premier Division",
      "name_status": "known",
      "association_code": "SYN",
      "organiser": "national_association",
      "competition_kind": "league",
      "tier": 1,
      "seasons": [
        {
          "id": "ssn_1",
          "label": "2026/27",
          "starts_on": "2026-08-01",
          "ends_on": "2027-05-31"
        }
      ],
      "sources": {
        "status": "included",
        "items": [
          {
            "source": "synthetic_alpha",
            "observed_at": null,
            "recorded_at": "2026-09-01T00:00:00Z",
            "precision": "unknown"
          },
          {
            "source": "synthetic_beta",
            "observed_at": null,
            "recorded_at": "2026-09-01T00:00:00Z",
            "precision": "unknown"
          }
        ]
      }
    }
  ],
  "page": {
    "next_cursor": null,
    "limit": 50
  }
}
```