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

# Get Usage Statistics

> Retrieve usage statistics for billing purposes. Returns statistics for document sent and document received actions, grouped by aggregation period (day/week/month). If no date parameters are provided, returns daily stats for all available data.



## OpenAPI

````yaml /openapi.json get /api/stats
openapi: 3.1.0
info:
  title: e-invoice.be Peppol Access Point API
  version: 1.1.0
  x-logo:
    url: https://e-invoice.be/einvoice.svg
servers:
  - url: https://api.e-invoice.be
    description: Production
security: []
paths:
  /api/stats:
    get:
      tags:
        - Tenant
      summary: Get Usage Statistics
      description: >-
        Retrieve usage statistics for billing purposes. Returns statistics for
        document sent and document received actions, grouped by aggregation
        period (day/week/month). If no date parameters are provided, returns
        daily stats for all available data.
      operationId: get_stats
      parameters:
        - name: start_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date
              - type: 'null'
            description: >-
              Start date in yyyy-mm-dd format. If not provided, queries from
              earliest available data.
            title: Start Date
          description: >-
            Start date in yyyy-mm-dd format. If not provided, queries from
            earliest available data.
        - name: end_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date
              - type: 'null'
            description: >-
              End date in yyyy-mm-dd format. If not provided, queries to latest
              available data.
            title: End Date
          description: >-
            End date in yyyy-mm-dd format. If not provided, queries to latest
            available data.
        - name: aggregation
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/StatsAggregationType'
              - type: 'null'
            description: 'Aggregation type: DAY, WEEK, or MONTH. Defaults to DAY.'
            default: DAY
            title: Aggregation
          description: 'Aggregation type: DAY, WEEK, or MONTH. Defaults to DAY.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsResponse'
        '400':
          description: 'Bad Request: Invalid date range or format'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 'Unauthorized: API key is missing, invalid, or inactive'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: 'Internal Server Error: Unexpected server error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - HTTPBearer: []
components:
  schemas:
    StatsAggregationType:
      type: string
      enum:
        - DAY
        - WEEK
        - MONTH
      title: StatsAggregationType
    StatsResponse:
      properties:
        tenant_id:
          type: string
          title: Tenant Id
          description: Tenant ID
        period_start:
          type: string
          format: date
          title: Period Start
          description: Start date of the period
        period_end:
          type: string
          format: date
          title: Period End
          description: End date of the period
        aggregation:
          $ref: '#/components/schemas/StatsAggregationType'
          description: Aggregation type used
        actions:
          items:
            $ref: '#/components/schemas/ActionStats'
          type: array
          title: Actions
          description: >-
            List of action statistics, one entry per aggregation period per
            action
        total_days:
          type: integer
          minimum: 1
          title: Total Days
          description: Number of days in the period
        average_daily_usage:
          type: number
          minimum: 0
          title: Average Daily Usage
          description: Average daily usage (total actions / total days)
        budget_estimation_days:
          type: number
          minimum: 0
          title: Budget Estimation Days
          description: >-
            Estimated days until credits run out (credit_balance /
            average_daily_usage). 0.0 if average_daily_usage is 0 or
            credit_balance is None
          default: 0
      type: object
      required:
        - tenant_id
        - period_start
        - period_end
        - aggregation
        - actions
        - total_days
        - average_daily_usage
      title: StatsResponse
      description: Statistics response for a tenant.
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
      type: object
      required:
        - detail
      title: ErrorResponse
      description: Error response model.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ActionStats:
      properties:
        action:
          $ref: '#/components/schemas/ActionType'
          description: Type of action
        stat_date:
          type: string
          format: date
          title: Stat Date
          description: >-
            The date/period this stat represents. For DAY aggregation this is
            the specific day, for WEEK it's the start of the week, for MONTH
            it's the first day of the month
        count:
          type: integer
          minimum: 0
          title: Count
          description: Number of occurrences of this action in this period
      type: object
      required:
        - action
        - stat_date
        - count
      title: ActionStats
      description: Statistics for a specific action in a specific time period.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ActionType:
      type: string
      enum:
        - DOCUMENT_SENT
        - DOCUMENT_RECEIVED
      title: ActionType
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````