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

# Get consumption history aggregated by month

> Get historical consumption data aggregated by month.

    Returns monthly statistics including:
    - Total consumption (GB)
    - Expected consumption (GB)
    - Device count
    - Average consumption per device (MB)
    - Count of devices exceeding limit (>100%)

    **Default behavior:**
    - If no dates provided: returns last 6 months (including current)
    - If only startMonth provided: returns from startMonth to current month
    - If both provided: returns specified range

    **Notes:**
    - Dates must be in format YYYY-MM
    - startMonth must be <= endMonth
    - Only includes valid consumption records (excludes not_found entries)



## OpenAPI

````yaml /generated/specs/diagnostics.json post /api/v1/consumption/history
openapi: 3.0.0
info:
  title: Raul API - Diagnostico
  description: Health, consumo, conectividad, SIMs, webhooks fallidos y estados tecnicos.
  version: 2.0.0
  contact: {}
servers:
  - url: https://api.raul.ugps.io
    description: Production
security: []
tags: []
paths:
  /api/v1/consumption/history:
    post:
      tags:
        - Consumption
      summary: Get consumption history aggregated by month
      description: |-
        Get historical consumption data aggregated by month.

            Returns monthly statistics including:
            - Total consumption (GB)
            - Expected consumption (GB)
            - Device count
            - Average consumption per device (MB)
            - Count of devices exceeding limit (>100%)

            **Default behavior:**
            - If no dates provided: returns last 6 months (including current)
            - If only startMonth provided: returns from startMonth to current month
            - If both provided: returns specified range

            **Notes:**
            - Dates must be in format YYYY-MM
            - startMonth must be <= endMonth
            - Only includes valid consumption records (excludes not_found entries)
      operationId: ConsumptionController_getConsumptionHistory
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsumptionHistoryRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MonthlyConsumptionDto'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmnifyErrorDto'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmnifyErrorDto'
      security:
        - bearerAuth: []
components:
  schemas:
    ConsumptionHistoryRequestDto:
      type: object
      properties:
        startMonth:
          type: string
          description: 'Mes inicial en formato YYYY-MM (opcional, default: hace 6 meses)'
          example: 2025-07
        endMonth:
          type: string
          description: 'Mes final en formato YYYY-MM (opcional, default: mes actual)'
          example: 2026-01
    MonthlyConsumptionDto:
      type: object
      properties:
        month:
          type: string
          description: Mes en formato YYYY-MM
          example: 2026-01
        totalConsumption:
          type: number
          description: Consumo total del mes en GB
          example: 125.5
        expectedConsumption:
          type: number
          description: Consumo esperado del mes en GB
          example: 100
        deviceCount:
          type: number
          description: Cantidad de dispositivos activos en el mes
          example: 120
        avgPerDevice:
          type: number
          description: Promedio de consumo por dispositivo en MB
          example: 1046
        overLimitCount:
          type: number
          description: Cantidad de dispositivos que excedieron el límite (>100%)
          example: 5
      required:
        - month
        - totalConsumption
        - expectedConsumption
        - deviceCount
        - avgPerDevice
        - overLimitCount
    EmnifyErrorDto:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: string
      required:
        - error
        - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication

````