> ## 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.

# Monthly usage statement

> One line per space of the tenant: conversations and tasks, every metric and the AI cost of one month, in JSON or CSV, to invoice from.



## OpenAPI

````yaml openapi/en/control.json GET /v1/usage/statement
openapi: 3.1.0
info:
  title: Niadra control API
  version: '1'
  description: >-
    Tenants, projects, sources, keys, people, configuration and usage. It never
    receives customer content.
servers:
  - url: https://control.api.niadra.com
security: []
paths:
  /v1/usage/statement:
    get:
      summary: Monthly usage statement
      description: >-
        The month's usage per space, to invoice from: conversations and tasks,
        every metric and the AI

        cost; `format=csv` for a spreadsheet. It lists the spaces of the tenant
        that the caller's analysis,

        security or admin role covers: all of them for a role on the whole
        tenant, one for a role on one.


        **Authentication.** Person token issued by the control plane
        (`Authorization: Bearer <JWT>`), with the role the operation needs.
      operationId: usage_statement_v1_usage_statement_get
      parameters:
        - description: The UTC month, `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` (the default) or `csv`.'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageStatementOut'
            text/csv:
              schema:
                type: string
          description: The month's statement.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: The request does not match the contract.
      security:
        - personToken: []
components:
  schemas:
    UsageStatementOut:
      additionalProperties: false
      properties:
        lines:
          description: >-
            One line per space of the tenant that existed in the month, with or
            without usage.
          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: RFC 9457 problem details; `code` comes from the versioned error catalog.
      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: What the space's AI calls cost Niadra, in millionths of a dollar.
          title: Ai Cost Micros
          type: integer
        billable:
          description: Conversations and tasks of the month, the unit the price is set per.
          title: Billable
          type: integer
        environment:
          title: Environment
          type: string
        metrics:
          additionalProperties:
            type: integer
          description: Every metric of the month, by name.
          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

````