List tournaments

GET /v1/external/tournaments is the entry point of every integration: it is how you turn "my tournaments" into a list of tournament idx values that the other endpoints take. It filters by status and sport, pages with limit/offset, and returns rows ordered by startDate descending. Typical uses are a "current tournaments" strip on a club website, a season archive page, and the discovery step of a nightly export.

Request

GET /v1/external/tournaments?status=IN_PROGRESS&sport=PADEL&limit=10 HTTP/1.1
Host: api.setto.io
Authorization: Bearer setto_live_…

Query parameters

curl -s -G https://api.setto.io/v1/external/tournaments \
  -H "Authorization: Bearer $SETTO_API_TOKEN" \
  -d status=IN_PROGRESS \
  -d sport=PADEL \
  -d limit=10

Response

{
  "data": [
    {
      "idx": "3c9b7f52-6d41-4a8e-b1f0-2e7d5c9a4b18",
      "slug": "torneo-apertura-2026",
      "name": "Torneo Apertura 2026",
      "type": "TOURNAMENT",
      "sport": "PADEL",
      "status": "IN_PROGRESS",
      "startDate": "2026-09-18T00:00:00.000Z",
      "endDate": "2026-09-20T00:00:00.000Z",
      "timezone": "America/Monterrey",
      "matchDays": null,
      "isPublic": true,
      "isFormatComplete": true,
      "banner": "https://cdn.setto.io/banners/torneo-apertura-2026.jpg",
      "displayPoints": true,
      "inscriptionCost": 900,
      "totalPrize": 40000,
      "createdAt": "2026-06-02T18:21:07.442Z",
      "publicUrl": "https://www.setto.io/t/torneo-apertura-2026",
      "organization": {
        "idx": "6f1d9c2e-4a7b-4f3d-9d2c-8b5e1a0f7c43",
        "name": "Club Padel Monterrey",
        "slug": "club-padel-monterrey"
      }
    }
  ],
  "meta": { "limit": 10, "offset": 0, "total": 1 }
}

The data rows are full tournament objects — the same shape getTournament returns — minus any relations, since this endpoint populates nothing by default.

The field whose shape depends on the sport is sportSettings: a FUTBOL tournament carries an object there, and PADEL, TENNIS and PICKLEBALL tournaments carry null. standingColumns follows the sport too — a FUTBOL row can list GOALS_FOR, GOALS_AGAINST and GOAL_DIFFERENCE, which never appear on a racket tournament (see Data model).

{
  "sport": "FUTBOL",
  "type": "TOURNAMENT",
  "sportSettings": {
    "modality": "F7",
    "extraTime": true,
    "matchMinutes": 50,
    "h2hRequiresCompleteSubset": true,
    "forfeitScore": 3,
    "fairPlayWeights": null
  }
}

Tips and pitfalls

• Drafts and archives are included. With no status filter you get DRAFT and ARCHIVED tournaments too. A public "what's on" strip almost always wants status=IN_PROGRESS plus status=UPCOMING — two calls, since status takes a single value.
• sport=FUTBOL selects the fútbol (soccer) tournaments. Those rows always carry type: "TOURNAMENT" and a non-null sportSettings, register teams rather than pairs, and are never part of a circuit. Treat the enum as open — fall through on a sport you do not recognise instead of throwing.
• isPublic: false is still returned. It tells you the organizer has turned the public page off; the API does not filter on it. If you are mirroring the public site, skip those rows yourself.
• What the list holds depends on the token. An organization token lists that organization's tournaments (including the ones shared into it); a personal token lists every tournament its owner manages right now, personal tournaments included. If an expected tournament is missing from an organization token's list, it probably belongs to a user rather than to the organization: use a personal token to reach it. With a personal token, each row's organization is the tournament's home organization, or null for a personal tournament.
• Do not populate here. club is the only allowed relation, and on a page of 100 rows it is 100 joins. Fetch the club once with getTournament instead.
• Page with limit=100 for exports, and de-duplicate on idx — see Pagination.
• Sort is startDate descending, so "the current tournament" is usually data[0] when you filter by status=IN_PROGRESS.

Related

• Get a tournament — the detail call.
• Pagination — walking a full archive.
• Reference: listTournaments.

MCP tool: list_tournaments