Listar Chamadas

O endpoint GET /api/calls lista as chamadas do seu projeto em um período, com paginação. Use-o para construir relatórios, dashboards de uso e conciliação de faturamento.

Requisição

GET /api/calls?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD

Cabeçalhos:

Cabeçalho	Obrigatório	Descrição
Authorization	Sim	Bearer SUA_API_KEY

Parâmetros de consulta:

Parâmetro	Tipo	Obrigatório	Descrição
startDate	string (YYYY-MM-DD)	Sim	Data inicial do período de busca. Exemplo: 2026-08-01
endDate	string (YYYY-MM-DD)	Sim	Data final do período de busca. Exemplo: 2026-08-30
page	number	Não	Página da paginação. Padrão: 1
limit	number	Não	Itens por página. Padrão: 10. Máximo: 100

startDate e endDate são obrigatórios

Sem esses dois parâmetros a API retorna 400 com a mensagem startDate and endDate are required.

Exemplos

cURL

curl -X GET "https://api.videochamada.com.br/api/calls?startDate=2026-08-01&endDate=2026-08-30&page=1&limit=20" \
  -H "Authorization: Bearer SUA_API_KEY"

Python (requests)

import requests

response = requests.get(
    "https://api.videochamada.com.br/api/calls",
    headers={"Authorization": "Bearer SUA_API_KEY"},
    params={
        "startDate": "2026-08-01",
        "endDate": "2026-08-30",
        "page": 1,
        "limit": 20,
    },
)
print(response.json())

Node.js (axios)

const axios = require('axios');

const response = await axios.get('https://api.videochamada.com.br/api/calls', {
  headers: { Authorization: 'Bearer SUA_API_KEY' },
  params: {
    startDate: '2026-08-01',
    endDate: '2026-08-30',
    page: 1,
    limit: 20,
  },
});
console.log(response.data);

Resposta

Exemplo de resposta:

{
  "data": [
    {
      "id": "9f3b2a1c-7d4e-4c8a-b5f6-2e1d0c9b8a7f",
      "status": "ended",
      "created": "2026-08-16T10:00:00.000Z",
      "started": "2026-08-16T10:05:00.000Z",
      "ended": "2026-08-16T10:35:00.000Z",
      "expiresAt": "2026-08-16T12:00:00.000Z",
      "totalBillableMinutes": "60.00",
      "recording": true
    },
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "status": "active",
      "created": "2026-08-16T11:00:00.000Z",
      "started": "2026-08-16T11:02:00.000Z",
      "ended": null,
      "expiresAt": "2026-08-16T13:00:00.000Z",
      "totalBillableMinutes": "15.50",
      "recording": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "totalPages": 8
  }
}

Campos do objeto de chamada:

Campo	Descrição
id	Identificador único da chamada (UUID)
status	Status atual: created, active ou ended
created	Data e hora de criação da chamada
started	Data e hora de início (quando o primeiro participante entrou)
ended	Data e hora de encerramento (null se ainda não encerrada)
expiresAt	Data e hora de expiração do link
totalBillableMinutes	Total de minutos faturáveis, como string decimal (ex.: "60.00")
recording	Valor resolvido da gravação para a chamada
—	O campo url não é retornado na listagem (apenas na criação da chamada). Se precisar do link, monte-o como https://{sua-organizacao}.videochamada.com.br/chamada/{id} (com domínio personalizado ativo, use-o no lugar do subdomínio)

Campos do objeto de paginação:

Campo	Descrição
page	Número da página atual
limit	Quantidade de itens por página
total	Total de chamadas no período
totalPages	Total de páginas

Erros

Status	Mensagem	Quando ocorre
400	startDate and endDate are required	Os parâmetros startDate e/ou endDate não foram enviados
401	Invalid API key	Chave inválida ou revogada, ou IP fora da lista de IPs permitidos da chave

Boas práticas

• Período de busca: use intervalos razoáveis para evitar respostas muito grandes. Recomenda-se buscar no máximo 90 dias por vez.
• Formato de data: use sempre YYYY-MM-DD (exemplo: 2026-08-01).
• Paginação: para grandes volumes, percorra as páginas usando page e limit em vez de aumentar limit além do necessário (o máximo é 100).
• Dashboards e relatórios: este endpoint é a base ideal para relatórios de uso; para o estado em tempo real de uma chamada específica, prefira GET /api/calls/{id}/status.