Eventos

Endpoint unificado para listar e pesquisar eventos com filtragem, paginação e busca.

GET /api/v1/events

AutenticaçãoPermalink for this section

Requer API key via header X-API-Key, header Authorization: Bearer ou parâmetro de consulta api_key. Disponível para todos os tiers.

Parâmetros de ConsultaPermalink for this section

Headers de RespostaPermalink for this section

Todas as respostas incluem headers padrão de rate limit e metadados:

Objeto EventPermalink for this section

Objeto Game StatePermalink for this section

Incluído quando o evento está ao vivo e tem dados de placar:

Exemplos de RequisiçõesPermalink for this section

Listar próximos eventos da NBA e NFLPermalink for this section

curl -X GET "https://api.sharpapi.io/api/v1/events?sport=basketball,football&league=nba,nfl&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  'https://api.sharpapi.io/api/v1/events?sport=basketball,football&league=nba,nfl&limit=20',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data, meta } = await response.json();
console.log(`Found ${meta.total} events, showing ${meta.count}`);

import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/events',
    params={
        'sport': 'basketball,football',
        'league': 'nba,nfl',
        'limit': 20
    },
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
data = response.json()
print(f"Found {data['meta']['total']} events")

Obter apenas eventos ao vivoPermalink for this section

curl -X GET "https://api.sharpapi.io/api/v1/events?is_live=true" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  'https://api.sharpapi.io/api/v1/events?is_live=true',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();
console.log(`${data.length} live events`);

import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/events',
    params={'live': 'true'},
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
live_events = response.json()['data']

Pesquisar por uma equipePermalink for this section

curl -X GET "https://api.sharpapi.io/api/v1/events?q=celtics" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  'https://api.sharpapi.io/api/v1/events?q=celtics',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();

import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/events',
    params={'q': 'celtics'},
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
results = response.json()['data']

Filtrar por data e sportsbookPermalink for this section

curl -X GET "https://api.sharpapi.io/api/v1/events?date=2026-02-08&sportsbook=draftkings,fanduel" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  'https://api.sharpapi.io/api/v1/events?date=2026-02-08&sportsbook=draftkings,fanduel',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data, meta } = await response.json();

import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/events',
    params={
        'date': '2026-02-08',
        'sportsbook': 'draftkings,fanduel'
    },
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
data = response.json()

RespostaPermalink for this section

Sucesso (200)Permalink for this section

{
  "data": [
    {
      "id": "evt_nba_bos_lal_20260208",
      "external_ids": {
        "draftkings": "33483200",
        "fanduel": "nba-bos-lal-20260208"
      },
      "sport": "basketball",
      "league": "nba",
      "home_team": "Boston Celtics",
      "away_team": "Los Angeles Lakers",
      "start_time": "2026-02-08T19:30:00Z",
      "status": "upcoming",
      "is_live": false,
      "book_count": 6,
      "markets": ["moneyline", "point_spread", "total_points"],
      "books": ["betmgm", "caesars", "draftkings", "fanduel"]
    },
    {
      "id": "evt_nba_gsw_mia_20260208",
      "external_ids": {
        "draftkings": "33483205"
      },
      "sport": "basketball",
      "league": "nba",
      "home_team": "Golden State Warriors",
      "away_team": "Miami Heat",
      "start_time": "2026-02-08T22:00:00Z",
      "status": "upcoming",
      "is_live": false,
      "book_count": 5,
      "markets": ["moneyline", "point_spread", "total_points"],
      "books": ["betmgm", "draftkings", "fanduel"]
    }
  ],
  "meta": {
    "count": 2,
    "total": 43,
    "pagination": {
      "limit": 50,
      "offset": 0,
      "has_more": true,
      "next_offset": 50
    },
    "updated_at": "2026-02-08T12:00:00Z",
    "filters": {
      "sport": ["basketball"],
      "league": ["nba"]
    }
  }
}

Resultados vazios (200): meta.storePermalink for this section

Quando /events retorna zero eventos, um bloco meta.store é adicionado explicando o motivo — com o mesmo vocabulário de reason de /odds, para que uma única verificação sirva para os dois endpoints. data é [] (antes de setembro de 2026 a lista padrão o serializava como null; ?status=final já retornava []), e pagination carrega count: 0 e total: 0:

{
  "data": [],
  "meta": {
    "store": {
      "ready": true,
      "events": 11064,
      "reason": "no_match"
    }
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 0,
    "total": 0,
    "has_more": false,
    "next_offset": null
  },
  "updated_at": "2026-09-07T02:41:18.552Z"
}

meta.store está presente apenas em resultados vazios; uma resposta com eventos não muda. Não há generation aqui, de propósito — esse contador pertence ao store de odds, que não alimenta este endpoint. Um valor desconhecido de league ou sportsbook é rejeitado com 400 invalid_filter em vez de respondido com uma página vazia.

Respostas de ErroPermalink for this section

401 Unauthorized

Se nenhuma chave for enviada, retorna missing_api_key; uma chave inválida retorna invalid_api_key.

{
  "error": {
    "code": "missing_api_key",
    "message": "API key required. Pass via X-API-Key header, api_key query parameter, or Bearer token.",
    "docs": "https://docs.sharpapi.io/en/authentication"
  }
}

400 Bad Request

{
  "error": {
    "code": "validation_error",
    "message": "Invalid date format. Use YYYY-MM-DD.",
    "docs": "https://docs.sharpapi.io/en/api-reference/events"
  }
}

429 Rate Limited

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Upgrade your tier for higher limits.",
    "docs": "https://docs.sharpapi.io/en/pricing"
  }
}

Migração de Endpoints AnterioresPermalink for this section

Vários sub-caminhos legados de eventos de versões anteriores da API são mantidos como sinalizadores de descontinuação — acessá-los retorna 410 Gone com uma dica legível por máquina apontando para o endpoint correto.

Formato da Resposta 410Permalink for this section

{
  "error": {
    "code": "unknown_endpoint",
    "message": "There is no /api/v1/events/search endpoint. Use GET /api/v1/events — results can be filtered with ?sport=, ?league=, and ?book= query parameters.",
    "correct_endpoint": "/api/v1/events",
    "docs": "https://docs.sharpapi.io/api-reference"
  }
}

Principais mudanças em relação às versões anterioresPermalink for this section

• Os nomes dos campos agora são snake_case (ex: home_team em vez de homeTeam)
• A resposta usa o envelope padrão data/meta em vez de um array events no nível superior
• Os parâmetros de consulta usam a forma singular (sport em vez de sports)
• A URL base é https://api.sharpapi.io (não https://sharpapi.io)
• A paginação agora inclui os campos has_more e next_offset

Correspondência de Eventos Entre SportsbooksPermalink for this section

O campo id é um identificador canônico de evento — o mesmo evento do mundo real recebe o mesmo id independentemente de qual sportsbook ele venha. Use-o como sua chave primária ao construir ferramentas de comparação entre sportsbooks. O campo external_ids mapeia cada sportsbook para seu ID nativo de evento para deep linking.

Veja Correspondência de Eventos para detalhes completos sobre como funcionam os IDs canônicos.

Endpoints RelacionadosPermalink for this section

• Detalhes do Evento - Obter detalhes completos de um único evento
• Odds do Evento - Obter todas as odds para um evento específico
• Mercados do Evento - Obter mercados disponíveis para um evento
• Snapshot de Odds - Obter odds atuais em todos os eventos