---
title: "Consultar consumo do contrato"
method: GET
path: "/contracts/{id}/usage"
tags: ["Contratos"]
---

# Consultar consumo do contrato

`GET /contracts/{id}/usage`

## Request

- Base URL: `https://api.tiflux.com/api/v2`
- URL: `https://api.tiflux.com/api/v2/contracts/{id}/usage`
- Auth: HTTP bearer

Retorna o consumo do contrato por ciclo de apuração: contratado, usado, saldo, excedente e percentual, com a quebra entre atendimento e plantão.

O ciclo vem do cronograma de faturamento do contrato, e não de um intervalo livre de datas: são retornados **os até 3 ciclos mais recentes iniciados até a `base_date`**, incluindo o ciclo que contém a data, que pode ainda estar aberto (`closed: false`).

Em Horas acumuladas, os ciclos param no primeiro ciclo ainda não faturado, porque o crédito acumulado dos ciclos seguintes ainda não foi apurado: uma `base_date` posterior a esse ciclo devolve os mesmos ciclos que a data atual.

`contracted`, `used`, `balance` e `percent_used` saem arredondados em 2 casas decimais.

Contratos das modalidades Livre e SaaS/Produto não têm ciclo de apuração e retornam `cycles` vazio.

## Query parameters

- `base_date` string, date

## Response `200`

- object: Consumo e saldo do contrato por ciclo de apuração
  - `contract_id` number, required: Identificador do contrato
  - `name` string, required: Nome do contrato
  - `modality` 'free' | 'credit' | 'shared' | 'hours' | 'recurrent' | 'per_ticket' | 'cumulative_hours', required: Modalidade do contrato
  - `last_consume_notification` string, nullable, required: Data do ciclo da última notificação de consumo enviada ao cliente
  - `cycles` object[], required: Ciclos de apuração, do mais recente para o mais antigo. Vazio nas modalidades sem ciclo (Livre e SaaS/Produto)
    - `billing_date` string, required: Último dia do ciclo apurado
    - `previous_billing_date` string, required: Data de fechamento do ciclo anterior
    - `closed` boolean, required: Indica se o ciclo já foi fechado
    - `closing_period` number, required: Periodicidade de fechamento, em meses
    - `cancelled` boolean, required: Indica se o aditivo do ciclo está cancelado
    - `contracted` union, required: Franquia contratada no ciclo: crédito em dinheiro, horas ou quantidade de tickets, conforme a modalidade
      - number
      - '--'
    - `used` union, required: Consumo apurado no ciclo, na mesma unidade da franquia
      - number
      - '--'
    - `balance` union, required: Saldo do ciclo (`contracted - used`). Negativo quando a franquia foi ultrapassada
      - number
      - '--'
    - `surplus` string, required: Valor do excedente do ciclo, em dinheiro. `"--"` sem permissão para ver valores
    - `percent_used` union, required: Percentual consumido da franquia. Nulo quando não há franquia no ciclo
      - number
      - '--'
    - `by_attendance` object, required: Duração apontada por tipo de atendimento, em minutos. Só é apurada na modalidade Crédito; nas demais vem zerada
      - `external` number, required: Externo
      - `remote` number, required: Remoto
      - `internal` number, required: Interno
      - `total_duration` number, required: Duração total apontada no ciclo
    - `used_shifts` number, nullable, required: Plantões consumidos no ciclo. Nulo nas modalidades que não controlam plantão

## Other responses

- `403`: ### **Problemas com permissão** Essa resposta significa que o seu usuário está autenticado corretamente, porém, não possui a permissão ou licença necessária para acessar essa rota
- `404`: ### **Contrato não encontrado**
- `422`: ### **Problemas com algum atributo informado**

## Changes

- **2026-10-06** `34239febc0a3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tiflux/apis/tiflux-official-api/changes/contracts/:id/usage/get.md)

---

[API](https://skmtc.dev/tiflux/apis/tiflux-official-api.md) - [All operations](https://skmtc.dev/tiflux/apis/tiflux-official-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tiflux/apis/tiflux-official-api/revisions/2936ac99a76d?raw)