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

# Extrato de uso do mês

> Uma linha por espaço do tenant: conversas e tarefas, todas as métricas e o custo de IA de um mês, em JSON ou CSV, para faturar.



## OpenAPI

````yaml openapi/pt/control.json GET /v1/usage/statement
openapi: 3.1.0
info:
  title: API de controle da Niadra
  version: '1'
  description: >-
    Tenants, projetos, fontes, chaves, pessoas, configuração e uso. Nunca recebe
    conteúdo de cliente.
servers:
  - url: https://control.api.niadra.com
security: []
paths:
  /v1/usage/statement:
    get:
      summary: Extrato de uso do mês
      description: >-
        O uso do mês por espaço do tenant, para faturar: conversas e tarefas,
        todas as métricas e o custo de IA, somados de um mês UTC dos agregados
        por hora; `format=csv` para uma planilha. Um espaço apagado durante o
        mês aparece nele; um apagado antes, não. O extrato diz o que foi usado,
        nunca um preço. Ele lista os espaços que o papel de análise, segurança
        ou admin de quem chama cobre: todos, para um papel no tenant inteiro;
        um, para um papel num espaço só.


        **Autenticação.** Token de pessoa emitido pelo controle (`Authorization:
        Bearer <JWT>`), com o papel que a operação pede.
      operationId: usage_statement_v1_usage_statement_get
      parameters:
        - description: O mês, em UTC, como `YYYY-MM`.
          in: query
          name: month
          required: true
          schema:
            description: The UTC month, `YYYY-MM`.
            pattern: ^\d{4}-\d{2}$
            title: Month
            type: string
        - in: query
          name: format
          required: false
          schema:
            default: json
            pattern: ^(json|csv)$
            title: Format
            type: string
          description: '`json` (o padrão) ou `csv`.'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageStatementOut'
            text/csv:
              schema:
                type: string
          description: O extrato do mês.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: O pedido não bate com o contrato.
      security:
        - personToken: []
components:
  schemas:
    UsageStatementOut:
      additionalProperties: false
      properties:
        lines:
          description: Uma linha por espaço do tenant que existiu no mês, com ou sem uso.
          items:
            $ref: '#/components/schemas/UsageStatementLine'
          title: Lines
          type: array
        month:
          title: Month
          type: string
      required:
        - month
        - lines
      title: UsageStatementOut
      type: object
    Problem:
      additionalProperties: false
      description: >-
        Detalhes do problema no formato da RFC 9457; `code` vem do catálogo de
        erros versionado.
      properties:
        code:
          title: Code
          type: string
        detail:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Detail
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Request Id
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          default: about:blank
          title: Type
          type: string
      required:
        - title
        - status
        - code
      title: Problem
      type: object
    UsageStatementLine:
      additionalProperties: false
      properties:
        ai_cost_micros:
          description: >-
            O que as chamadas de IA do espaço custaram à Niadra, em milionésimos
            de dólar.
          title: Ai Cost Micros
          type: integer
        billable:
          description: >-
            As conversas e tarefas do mês, a unidade pela qual o preço é
            definido.
          title: Billable
          type: integer
        environment:
          title: Environment
          type: string
        metrics:
          additionalProperties:
            type: integer
          description: Toda métrica do mês, por nome.
          title: Metrics
          type: object
        project_id:
          format: uuid
          title: Project Id
          type: string
        slug:
          title: Slug
          type: string
        space_id:
          format: uuid
          title: Space Id
          type: string
      required:
        - space_id
        - project_id
        - environment
        - slug
        - billable
        - ai_cost_micros
        - metrics
      title: UsageStatementLine
      type: object
  securitySchemes:
    personToken:
      type: http
      scheme: bearer
      bearerFormat: JWT

````