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

# Competitions

> Get all available competitions (leagues/tournaments) with event counts

<Info>
  **Public Endpoint**: No API key required
</Info>

Returns all competitions (leagues, tournaments, cups) across all sports. Each competition includes event counts and parent region information.

Use this endpoint to:

* Build competition selectors
* Display leagues with upcoming matches
* Filter events by competition
* Show popular leagues

## Query Parameters

<ParamField query="locale" type="string" default="en">
  Language for competition and region names. Supported: `en`, `es`, `pt`
</ParamField>

<ParamField query="regionId" type="string">
  Filter competitions by region ID

  Example: `6` for England
</ParamField>

<ParamField query="date" type="string">
  Filter competitions with events on specific date (YYYY-MM-DD)

  Example: `2025-11-08`

  <Warning>
    Cannot be used together with `startDate` or `endDate`. Choose either `date` for single-day filtering or `startDate`/`endDate` for range filtering.
  </Warning>
</ParamField>

<ParamField query="startDate" type="string">
  Filter competitions with events starting from this date

  <Warning>
    Cannot be used together with `date` parameter.
  </Warning>
</ParamField>

<ParamField query="endDate" type="string">
  Filter competitions with events ending on this date

  <Warning>
    Cannot be used together with `date` parameter.
  </Warning>
</ParamField>

<ParamField query="status" type="string" default="upcoming,live">
  Filter by event status. Pass multiple values with commas or repeat the parameter (e.g., `status=completed`). Defaults to upcoming + live events.
</ParamField>

<ParamField query="timezone" type="string">
  Timezone for date filtering

  Example: `America/New_York`
</ParamField>

## Response

<ResponseField name="data" type="array">
  <Expandable title="Competition Object">
    <ResponseField name="id" type="integer">
      Competition ID
    </ResponseField>

    <ResponseField name="caption" type="string">
      Competition name (localized using the `locale` parameter)

      Example: `Premier League`, `Champions League`
    </ResponseField>

    <ResponseField name="regionId" type="integer">
      Parent region ID
    </ResponseField>

    <ResponseField name="region" type="object">
      Region object with `id` and localized `caption`
    </ResponseField>

    <ResponseField name="_count" type="object">
      <Expandable title="Count Object">
        <ResponseField name="events" type="integer">
          Number of events in this competition
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

```bash theme={null}
curl "https://api.mrdoge.co/v2/competitions?regionId=6&date=2025-11-15&locale=en"
```

## Example Response

```json theme={null}
{
  "data": [
    {
      "id": 847,
      "caption": "Premier League",
      "regionId": 6,
      "region": {
        "id": 6,
        "caption": "England"
      },
      "_count": {
        "events": 4
      }
    },
    {
      "id": 29,
      "caption": "LaLiga",
      "regionId": 5,
      "region": {
        "id": 5,
        "caption": "Spain"
      },
      "_count": {
        "events": 4
      }
    }
  ]
}
```

## Use Cases

<CardGroup cols={2}>
  <Card title="Competition Selector" icon="list">
    Build dropdowns to let users filter events by league or tournament
  </Card>

  <Card title="League Overview" icon="trophy">
    Show all competitions in a specific region with upcoming match counts
  </Card>

  <Card title="Multi-Sport Coverage" icon="globe">
    Display which competitions are active across different sports
  </Card>

  <Card title="Schedule Widgets" icon="calendar">
    Create widgets showing leagues with the most events on specific dates
  </Card>
</CardGroup>

<Note>
  Competition data is optimized for fast responses. Combine with the [Events endpoint](/api-reference/sports/events) to build complete league schedules.
</Note>


## OpenAPI

````yaml /api-reference/openapi.json GET /v2/competitions
openapi: 3.1.0
info:
  title: Mr. Doge API
  description: >-
    Comprehensive sports betting odds, AI predictions, and live data API
    covering 8 major sports with real-time updates and value betting
    recommendations.
  version: 1.0.0
  contact:
    name: Mr. Doge Support
    email: support@mrdoge.co
    url: https://mrdoge.co
servers:
  - url: https://api.mrdoge.co
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Odds
    description: Endpoints for accessing sports events, odds, and betting markets
  - name: AI
    description: AI-powered betting recommendations and value opportunities
paths:
  /v2/competitions:
    get:
      tags:
        - Odds
      summary: List Competitions
      description: Get all available competitions (leagues/tournaments) with event counts.
      parameters:
        - name: regionId
          in: query
          description: Filter by region ID
          schema:
            type: string
            example: '1'
        - name: date
          in: query
          description: Filter competitions with events on specific date (YYYY-MM-DD)
          schema:
            type: string
            format: date
            example: '2025-11-08'
        - name: startDate
          in: query
          description: Filter competitions with events starting from this date
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          description: Filter competitions with events ending on this date
          schema:
            type: string
            format: date
        - name: status
          in: query
          description: >-
            Filter competitions by event status (repeat or comma-separate
            values). Defaults to upcoming and live events.
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - upcoming
                - live
                - completed
        - name: timezone
          in: query
          description: Timezone for date filtering
          schema:
            type: string
            example: America/New_York
      responses:
        '200':
          description: List of competitions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Competition'
      security: []
components:
  schemas:
    Competition:
      type: object
      properties:
        id:
          type: integer
          example: 1
        caption:
          type: string
          example: Premier League
        regionId:
          type: integer
          example: 1
        region:
          $ref: '#/components/schemas/Region'
        _count:
          type: object
          properties:
            events:
              type: integer
              example: 38
    Region:
      type: object
      properties:
        id:
          type: integer
          example: 1
        caption:
          type: string
          example: England
        _count:
          type: object
          properties:
            competitions:
              type: integer
              example: 5
            events:
              type: integer
              example: 120
        availableSports:
          type: array
          items:
            type: string
          example:
            - soccer
            - tennis
        competitions:
          type: array
          items:
            $ref: '#/components/schemas/Competition'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Use your API key from the Mr. Doge dashboard. Format: `Bearer
        sk_live_...` or `Bearer sk_test_...`

````