> ## Documentation Index
> Fetch the complete documentation index at: https://docs.messora.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /account/usage

> Uso mensal de créditos e saldo restante da conta autenticada.

## Quando usar

Chame antes de um `/batch` ou `/crawl` grande para confirmar que há saldo, ou
depois de uma execução para conciliar o que foi de fato cobrado. Todos os campos
são da conta por trás da `X-API-Key` enviada — não existe seletor de conta.

## Como ler os números

`credits_used` é a soma do consumo cobrado no **mês-calendário corrente**.
Zera no dia 1º.

`remaining_credits` é o saldo real, **não** `monthly_credits - credits_used`.
Top-ups somam ao saldo sem alterar a franquia mensal, então os dois valores
divergem assim que você compra créditos avulsos.

`breakdown` agrupa o consumo do mês por endpoint, permitindo separar a cobrança
de um `/crawl` da de um `/scrape`.

## Rate limit

30 requisições por minuto, por conta. Este endpoint não serve para polling —
use `GET /jobs/{job_id}` para acompanhar o progresso de um job.

## Exemplo

```bash cURL theme={null}
curl https://api.messora.dev/account/usage \
  -H "X-API-Key: YOUR_API_KEY"
```

## Relacionado

A tool MCP `get_usage` devolve os mesmos dados pelo protocolo MCP —
veja [Integração MCP](/pt-BR/mcp).


## OpenAPI

````yaml GET /account/usage
openapi: 3.1.0
info:
  description: >-
    ## Messora API


    Scraping com evasão anti-bot nativa. Retorna conteúdo limpo (Markdown / JSON
    estruturado / raw HTML).


    **Autenticação:** header `X-API-Key` em todas as rotas.


    **Créditos:** scrape markdown/raw = 1; JSON estruturado = 10; search = 1 por
    resultado; crawl = 1 por página bem-sucedida.
  summary: API de scraping LLM-ready com motor anti-bot nativo.
  title: Messora API
  version: 2.0.0
servers:
  - description: API pública do Messora
    url: https://api.messora.dev
security: []
paths:
  /account/usage:
    servers:
      - description: API pública do Messora
        url: https://api.messora.dev
    get:
      tags:
        - Uso
      summary: Retorna uso mensal de créditos da conta
      description: >-
        Retorna o consumo de créditos do mês corrente para a conta autenticada.
        O consumo vem de usage_records e o saldo disponível vem de
        accounts.balance.


        O campo `credits_used` é a soma de todos os scrapes bem-sucedidos do
        mês; `remaining_credits` inclui créditos de top-up.
      operationId: get_account_usage_account_usage_get
      responses:
        '200':
          content:
            application/json:
              example:
                breakdown:
                  - credits_used: 15
                    endpoint: /scrape
                  - credits_used: 8
                    endpoint: /batch
                credits_used: 23
                monthly_credits: 100
                plan: free
                remaining_credits: 77
              schema:
                $ref: '#/components/schemas/AccountUsageResponse'
          description: Uso mensal da conta
        '401':
          description: X-API-Key ausente
        '403':
          description: API key inválida ou revogada
        '429':
          description: Rate limit por tenant excedido (USAGE_RATE_LIMIT=30/min)
      security:
        - APIKeyHeader: []
components:
  schemas:
    AccountUsageResponse:
      description: Resposta de `GET /account/usage` (RF-010 / D-11).
      properties:
        breakdown:
          description: Consumo do mês agrupado por endpoint.
          items:
            $ref: '#/components/schemas/UsageBreakdownItem'
          title: Breakdown
          type: array
        credits_used:
          description: Soma dos créditos consumidos no mês-calendário corrente.
          title: Credits Used
          type: integer
        monthly_credits:
          description: Franquia mensal do plano.
          title: Monthly Credits
          type: integer
        plan:
          description: 'Plano da conta: free, starter, growth ou scale.'
          title: Plan
          type: string
        remaining_credits:
          description: >-
            Saldo disponível em accounts.balance. Inclui créditos de top-up, por
            isso não é necessariamente monthly_credits - credits_used.
          title: Remaining Credits
          type: integer
      required:
        - plan
        - monthly_credits
        - credits_used
        - remaining_credits
        - breakdown
      title: AccountUsageResponse
      type: object
    UsageBreakdownItem:
      description: Consumo de créditos agregado por endpoint no mês corrente.
      properties:
        credits_used:
          description: Créditos consumidos por essa rota no mês.
          title: Credits Used
          type: integer
        endpoint:
          description: Rota que consumiu créditos, como /scrape.
          title: Endpoint
          type: string
      required:
        - endpoint
        - credits_used
      title: UsageBreakdownItem
      type: object
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey

````