Eventos
Endpoint unificado para listar e pesquisar eventos com filtragem, paginação e busca.
GET /api/v1/eventsEste endpoint substitui os endpoints anteriores /schedule, /events/live e /events/search. Toda a funcionalidade desses endpoints agora está disponível aqui através de parâmetros de consulta. Veja as Notas de Migração abaixo.
AutenticaçãoLink permanente para esta seção
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 ConsultaLink permanente para esta seção
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
sport | string | todos | Filtrar por esporte. Separados por vírgula para múltiplos (ex: basketball,football) |
league | string | todas | Filtrar por liga. Separados por vírgula para múltiplos (ex: nba,nfl) |
sportsbook | string | todos | Filtrar por sportsbook (ex: draftkings,pinnacle) |
status | string | — | Filtrar por estado do ciclo de vida: upcoming, live ou final. Omitir para o conjunto padrão (upcoming + live). final retorna as conclusões retidas. Um valor não reconhecido é rejeitado com 400 validation_error. |
is_live | boolean | — | true = apenas ao vivo, false = apenas pré-jogo, omitir = ambos |
date | string | — | Filtrar por data no formato YYYY-MM-DD |
q | string | — | Consulta de busca correspondendo a nomes de equipes ou nomes de eventos |
limit | integer | 50 | Resultados por página (máx 200) |
offset | integer | 0 | Offset de paginação |
Os parâmetros de consulta usam a forma singular e valores separados por vírgula para múltiplos: sport=basketball,football, e não sports=basketball&sports=football.
Headers de RespostaLink permanente para esta seção
Todas as respostas incluem headers padrão de rate limit e metadados:
| Header | Descrição |
|---|---|
X-RateLimit-Limit | Máximo de requisições por minuto para o seu tier |
X-RateLimit-Remaining | Requisições restantes na janela atual |
X-RateLimit-Reset | Timestamp Unix de quando a janela de rate limit é reiniciada |
X-Data-Delay | Atraso de dados para o seu tier (ex: 0s, 60s) |
X-Request-Id | Identificador único da requisição para depuração |
Objeto EventLink permanente para esta seção
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identificador canônico do evento — o mesmo para todos os sportsbooks que cobrem este evento. Use como sua chave primária para correspondência entre sportsbooks. Veja Correspondência de Eventos. |
external_ids | object | Mapa de ID do sportsbook para o ID nativo do evento naquele sportsbook (ex: {"draftkings": "33483153"}). Use estes para deep linking de volta às páginas dos sportsbooks. |
sport | string | Identificador do esporte (ex: basketball, football) |
league | string | Slug da liga (ex: nba, nfl) |
home_team | string | Nome da equipe da casa |
away_team | string | Nome da equipe visitante |
start_time | string | Horário de início do evento em ISO 8601. Ausente em um evento finalizado servido a partir do armazenamento de retenção — verifique a presença da chave, não o status. |
completed_at | string | Horário de conclusão em ISO 8601. Presente apenas em linhas com status: "final". |
status | string | Status do evento: upcoming, live ou final. final só é retornado quando solicitado com ?status=final. |
is_live | boolean | Se o evento está atualmente ao vivo |
book_count | integer | Número de sportsbooks com odds para este evento |
markets | string[] | Array ordenado dos tipos de mercado disponíveis (ex: ["moneyline", "point_spread", "total_points"]) |
books | string[] | Array ordenado de IDs de sportsbooks com odds para este evento |
game_state | object | undefined | Estado do jogo ao vivo (presente apenas para eventos ao vivo com placar) |
Eventos finalizados. ?status=final retorna as conclusões retidas, da mais recente para a mais antiga — um conjunto de resultados separado, que não faz parte da lista não filtrada. Essas linhas omitem start_time (nenhum horário de início é retido para elas) e trazem completed_at no lugar. Um evento recém-finalizado cujas odds ainda estão em cache mantém seu start_time real, portanto verifique se a chave está presente em vez de ramificar pelo status.
Objeto Game StateLink permanente para esta seção
Incluído quando o evento está ao vivo e tem dados de placar:
| Campo | Tipo | Descrição |
|---|---|---|
home_score | number | Placar da equipe da casa |
away_score | number | null | Placar da equipe visitante |
period | string | null | Período atual (ex: Q3, 2nd, 3rd Period) |
clock | string | null | Tempo restante (ex: 5:42) |
score_type | string | Tipo de placar (ex: game_points, match) |
possession | string | null | Equipe com posse de bola (home ou away) |
is_timeout | boolean | null | Se um timeout está em andamento |
power_play | string | null | Informação de power play (home ou away, hóquei) |
last_play | string | null | Descrição da última jogada |
Exemplos de RequisiçõesLink permanente para esta seção
Listar próximos eventos da NBA e NFLLink permanente para esta seção
cURL
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"Obter apenas eventos ao vivoLink permanente para esta seção
cURL
curl -X GET "https://api.sharpapi.io/api/v1/events?is_live=true" \
-H "X-API-Key: YOUR_API_KEY"Pesquisar por uma equipeLink permanente para esta seção
cURL
curl -X GET "https://api.sharpapi.io/api/v1/events?q=celtics" \
-H "X-API-Key: YOUR_API_KEY"Filtrar por data e sportsbookLink permanente para esta seção
cURL
curl -X GET "https://api.sharpapi.io/api/v1/events?date=2026-02-08&sportsbook=draftkings,fanduel" \
-H "X-API-Key: YOUR_API_KEY"RespostaLink permanente para esta seção
Sucesso (200)Link permanente para esta seção
{
"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.storeLink permanente para esta seção
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"
}reason | Significado | O que fazer |
|---|---|---|
warming | A instância que respondeu não concluiu nenhum ciclo de atualização desde a última mudança de modo — nada foi carregado ainda | Tentar novamente |
store_empty | A instância está pronta, mas o cache de eventos a partir do qual esta página foi construída está vazio | Tentar novamente — não trate a página vazia como definitiva |
no_match | A instância está pronta e o cache está populado; seus filtros não corresponderam a nada | Definitivo — tentar novamente não mudará a resposta |
| Campo | Tipo | Significado |
|---|---|---|
ready | boolean | Pelo menos um ciclo de atualização foi concluído desde a última mudança de modo da instância. |
events | integer | Eventos no cache a partir do qual esta página foi construída, independentemente dos seus filtros. Páginas com ?status=final são servidas a partir do store de eventos encerrados e informam o tamanho desse store. |
reason | string | warming, store_empty ou no_match — veja acima. |
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 ErroLink permanente para esta seção
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 AnterioresLink permanente para esta seção
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.
| Caminho Descontinuado | Use no Lugar |
|---|---|
GET /events/search?q=celtics | GET /events?q=celtics |
GET /events/list | GET /events |
GET /events/all | GET /events |
GET /events/find | GET /events |
Formato da Resposta 410Link permanente para esta seção
{
"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"
}
}Respostas pré-v1 usavam nomes de campos em camelCase (homeTeam, awayTeam, isLive, bookCount). A API v1 usa snake_case exclusivamente (home_team, away_team, is_live, book_count). Atualize o código do seu cliente conforme necessário.
Principais mudanças em relação às versões anterioresLink permanente para esta seção
- Os nomes dos campos agora são snake_case (ex:
home_teamem vez dehomeTeam) - A resposta usa o envelope padrão
data/metaem vez de um arrayeventsno nível superior - Os parâmetros de consulta usam a forma singular (
sportem vez desports) - A URL base é
https://api.sharpapi.io(nãohttps://sharpapi.io) - A paginação agora inclui os campos
has_moreenext_offset
Correspondência de Eventos Entre SportsbooksLink permanente para esta seção
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 RelacionadosLink permanente para esta seção
- 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