> ## 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.

# Trending Events

> Get today's most-viewed events

<Warning>
  **Requires Authentication**: This endpoint requires an API key and costs **1 credit** per request.
</Warning>

Returns the top 5 most-viewed **upcoming and live** events for today. Perfect for discovering popular betting opportunities and showing users what everyone else is looking at.

Events are ranked by view count and include basic event details with key markets. This is a lightweight endpoint optimized for speed - for full AI analysis, use the [Event Details](/api-reference/sports/event-details) endpoint.

Use the `status` parameter to filter by event status (e.g., `status=completed` to see the most-viewed completed events of the day).

<Info>
  Include the `locale` query parameter (`en`, `es`, or `pt`) to localize team, competition, and region names.
</Info>

## Authorization

<ParamField header="Authorization" type="string" required default="Bearer " placeholder="Bearer sk_live_...">
  Your API key for authentication
</ParamField>

## Query Parameters

<ParamField query="timezone" type="string">
  Timezone for calculating "today"

  Example: `America/New_York`, `Europe/London`

  Default: UTC
</ParamField>

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

<ParamField query="sport" type="string">
  Filter by sport name

  Options: `soccer`, `basketball`, `baseball`, `tennis`, `american-football`, `ice-hockey`, `volleyball`, `handball`
</ParamField>

<ParamField query="status" type="string" default="upcoming,live">
  Filter by event status

  Options: `upcoming`, `live`, `completed`

  Pass multiple statuses with commas: `status=upcoming,live` or `status=completed`

  Default: Returns `upcoming` and `live` events
</ParamField>

## Response

Returns an array of the top 5 most-viewed events for today, filtered by status (default: upcoming and live).

Each event includes:

* Basic event details (teams, competition, region, status)
* Markets and odds (SOCCER\_MATCH\_RESULT and SOCCER\_UNDER\_OVER only)
* Current view count

<Note>
  **Lightweight Endpoint**: This endpoint does NOT include:

  * Live stats (`stats` field)
  * AI betting recommendations
  * Mr. Doge picks
  * Match simulations or analysis

  For complete event data with AI analysis, use the [Event Details](/api-reference/sports/event-details) endpoint.
</Note>

## Example Request

```bash theme={null}
curl -H "Authorization: Bearer sk_live_..." \
  "https://api.mrdoge.co/v2/matches/trending?sport=soccer&locale=en"
```

```bash Get Completed Events (Most Viewed Today) theme={null}
curl -H "Authorization: Bearer sk_live_..." \
  "https://api.mrdoge.co/v2/matches/trending?status=completed&sport=soccer&locale=en"
```

## Example Response

```json theme={null}
{
  "data": [
    {
      "id": "<string>",
      "competitionId": 847,
      "startDateTime": "2025-11-15T15:00:00.000Z",
      "status": "upcoming",
      "views": 104,
      "sport": {
        "name": "soccer"
      },
      "homeTeam": {
        "id": 104932,
        "name": "Manchester City"
      },
      "awayTeam": {
        "id": 158346,
        "name": "Liverpool"
      },
      "competition": {
        "id": 847,
        "caption": "Premier League"
      },
      "markets": [
        {
          "id": "<string>",
          "eventId": "<string>",
          "betTypeSysname": "SOCCER_UNDER_OVER",
          "betItems": [
            {
              "id": "<string>",
              "code": "U",
              "caption": "Under 2.5",
              "instanceCaption": "2.5",
              "price": 1.62,
              "oddsText": "1.62",
              "isAvailable": true
            },
            {
              "id": "<string>",
              "code": "O",
              "caption": "Over 2.5",
              "instanceCaption": "2.5",
              "price": 2.2,
              "oddsText": "2.20",
              "isAvailable": true
            }
          ]
        }
      ],
      "region": {
        "id": 6,
        "caption": "England"
      }
    }
  ],
  "count": 5
}
```

## Use Cases

<CardGroup cols={2}>
  <Card title="Popular Events" icon="fire">
    Show users what events are trending
  </Card>

  <Card title="Featured Picks" icon="star">
    Highlight AI recommendations for popular games
  </Card>

  <Card title="Discovery" icon="compass">
    Help users find interesting betting opportunities
  </Card>

  <Card title="Social Proof" icon="users">
    Show which events have the most interest
  </Card>
</CardGroup>


## OpenAPI

````yaml /api-reference/openapi.json GET /v2/matches/trending
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/matches/trending:
    get:
      tags:
        - Odds
      summary: Get Trending Events
      description: >-
        Get today's most-viewed events with AI picks and recommendations. Useful
        for discovering popular betting opportunities.
      parameters:
        - name: timezone
          in: query
          description: Timezone for 'today' calculation
          schema:
            type: string
            example: America/New_York
        - name: sport
          in: query
          description: Filter by sport name
          schema:
            type: string
            example: soccer
      responses:
        '200':
          description: Trending events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrendingEvent'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    TrendingEvent:
      allOf:
        - $ref: '#/components/schemas/Event'
        - type: object
          properties:
            mrDogePick:
              $ref: '#/components/schemas/MrDogePick'
            bettingRecommendations:
              type: array
              items:
                $ref: '#/components/schemas/BettingRecommendation'
    Event:
      type: object
      properties:
        id:
          type: string
          example: '123456'
        competitionId:
          type: integer
          example: 1
        homeTeamId:
          type: integer
          example: 100
          deprecated: true
        awayTeamId:
          type: integer
          example: 101
          deprecated: true
        regionId:
          type: integer
          example: 1
        sportId:
          type: integer
          example: 1
        startDateTime:
          type: string
          format: date-time
          example: '2025-11-08T15:00:00Z'
        status:
          type: string
          enum:
            - upcoming
            - live
            - completed
          example: upcoming
        views:
          type: integer
          example: 1250
        metadata:
          type: object
          description: Sport-specific event metadata including teams, markets, and odds
          properties:
            sportName:
              type: string
              example: soccer
            homeTeamName:
              type: string
              example: Arsenal
            awayTeamName:
              type: string
              example: Chelsea
    MrDogePick:
      type: object
      properties:
        id:
          type: string
          example: pick_123456
        pickType:
          type: string
          enum:
            - single
            - parlay
          example: parlay
        recommendations:
          type: array
          items:
            $ref: '#/components/schemas/BettingRecommendation'
        totalOdds:
          type: number
          format: float
          example: 8.5
          description: Combined odds for parlay (product of all recommendation odds)
        settled:
          type: boolean
          example: false
        result:
          type: string
          enum:
            - won
            - lost
            - push
          nullable: true
    BettingRecommendation:
      type: object
      properties:
        id:
          type: string
          example: rec_123456
        eventId:
          type: string
          example: '123456'
        marketId:
          type: string
          example: mkt_123456
        betItemId:
          type: string
          example: bet_123456
        outcome:
          type: string
          example: Home Win
        odds:
          type: number
          format: float
          example: 2.1
        confidence:
          type: string
          enum:
            - High
            - Medium
            - Low
          example: High
        edgePercentage:
          type: number
          format: float
          example: 6.8
          description: Statistical edge over market odds
        kellyFraction:
          type: number
          format: float
          example: 0.032
          description: >-
            Optimal stake size using Kelly Criterion (10% fractional Kelly
            recommended)
        rationale:
          type: array
          items:
            type: string
          example:
            - Home team's excellent form (8 wins in last 10)
            - Away team struggling defensively (10 goals conceded in 3 games)
        riskFactors:
          type: array
          items:
            type: string
          example:
            - Away team has key players returning from injury
        dataSupport:
          type: array
          items:
            type: string
          example:
            - Simulation gives 52% home win probability vs 47.6% implied by odds
        settled:
          type: boolean
          example: false
        result:
          type: string
          enum:
            - won
            - lost
            - push
          nullable: true
    Error:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          type: string
          example: Invalid request parameters
        error:
          type: string
          example: Bad Request
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 401
            message: Invalid API key
            error: Unauthorized
  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_...`

````