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

# Get usage report

> Retrieve detailed usage statistics and analytics for a specific period.

**Metrics Included:**
- Total messages sent
- Delivery rates
- Breakdown by route
- Cost analysis
- Failure reasons

Retrieve detailed usage statistics and analytics for a specific period.

**Metrics Included:**

* Total messages sent
* Delivery rates
* Breakdown by route
* Cost analysis
* Failure reasons


## OpenAPI

````yaml GET /reports/usage
openapi: 3.1.0
info:
  title: Xerobi SMS Gateway API
  version: '2026-01-01'
  description: >-
    A modern, developer-friendly SMS Gateway API supporting transactional, OTP,
    promotional and bulk messaging.


    ## Overview


    The Xerobi SMS Gateway API enables you to send SMS messages programmatically
    with support for:


    - **Transactional SMS**: Account notifications, confirmations, alerts

    - **OTP Messages**: One-time passwords with optimized delivery routes

    - **Promotional SMS**: Marketing campaigns and announcements

    - **Bulk Messaging**: Send to thousands of recipients efficiently

    - **Templates**: Reusable message templates with variable substitution

    - **Webhooks**: Real-time delivery status notifications


    ## Authentication


    Authenticate using your API key as a Bearer token:


    ```bash

    curl -H "Authorization: Bearer sk_live_xxxxx" \
      -H "Xerobi-Version: 2026-01-01" \
      https://api.hixbe.com/sms/messages
    ```


    **API Key Types:**

    - `sk_live_*` - Production keys for live messaging

    - `sk_test_*` - Test keys for development (no actual SMS sent)


    Get your API keys from the [Xerobi
    Dashboard](https://dashboard.hixbe.com/api-keys).


    ## Rate Limits


    - **Standard accounts**: 100 requests/minute

    - **Business accounts**: 1,000 requests/minute

    - **Enterprise accounts**: Custom limits


    Rate limit headers are included in all responses:

    - `X-RateLimit-Limit`: Maximum requests per window

    - `X-RateLimit-Remaining`: Requests remaining

    - `X-RateLimit-Reset`: Unix timestamp when limit resets


    ## Message Routes


    Different routes optimize for delivery speed, reliability, and cost:


    | Route | Use Case | Delivery Speed | Cost |

    |-------|----------|----------------|------|

    | **otp** | One-time passwords | < 5 seconds | Premium |

    | **transactional** | Notifications, alerts | < 30 seconds | Standard |

    | **promotional** | Marketing messages | < 2 minutes | Economy |


    ## Phone Number Format


    Phone numbers must be in international format without + or spaces:

    - ✅ Correct: `8801712345678` (Bangladesh)

    - ✅ Correct: `14155551234` (USA)

    - ❌ Incorrect: `+880 171 234 5678`

    - ❌ Incorrect: `01712345678`


    ## Idempotency


    Include `Idempotency-Key` header to safely retry requests:


    ```bash

    curl -H "Idempotency-Key: unique-key-123" \
      -H "Authorization: Bearer sk_live_xxxxx" \
      ...
    ```


    ## Webhooks


    Receive real-time delivery updates via webhooks. Events include:

    - `message.queued` - Message accepted and queued

    - `message.sent` - Message sent to carrier

    - `message.delivered` - Successfully delivered

    - `message.failed` - Delivery failed


    ## Support


    Need help? Contact us:

    - Email: support@xerobi.com

    - Documentation: https://developer.hixbe.com

    - Status: https://status.hixbe.com
  contact:
    name: Xerobi Developer Support
    url: https://developer.hixbe.com
    email: support@xerobi.com
  termsOfService: https://hixbe.com/terms
  license:
    name: Commercial
    url: https://hixbe.com/license
servers:
  - url: https://api.hixbe.com/sms
    description: Production Server
  - url: https://api-sandbox.hixbe.com/sms
    description: Sandbox Server (test mode)
security:
  - bearerAuth: []
tags:
  - name: Messages
    description: Send and track individual SMS messages
  - name: Bulk
    description: CSV and list-based bulk sending for campaigns
  - name: Senders
    description: Manage sender IDs and registration
  - name: Templates
    description: Create and manage message templates with variables
  - name: Reports
    description: Delivery statistics and usage analytics
  - name: Account
    description: Balance, usage limits and account profile
  - name: Webhooks
    description: Configure delivery report callbacks
paths:
  /reports/usage:
    get:
      tags:
        - Reports
      summary: Get usage report
      description: |-
        Retrieve detailed usage statistics and analytics for a specific period.

        **Metrics Included:**
        - Total messages sent
        - Delivery rates
        - Breakdown by route
        - Cost analysis
        - Failure reasons
      operationId: getUsageReport
      parameters:
        - $ref: '#/components/parameters/Xerobi-Version'
        - name: period
          in: query
          required: true
          description: Report period
          schema:
            type: string
            enum:
              - daily
              - weekly
              - monthly
              - yearly
        - name: start_date
          in: query
          description: Period start date (YYYY-MM-DD)
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          description: Period end date (YYYY-MM-DD)
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Usage report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageReport'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    Xerobi-Version:
      name: Xerobi-Version
      in: header
      description: >-
        API version in YYYY-MM-DD format. Using the latest version ensures
        access to newest features.
      required: true
      schema:
        type: string
        default: '2026-01-01'
        pattern: ^\d{4}-\d{2}-\d{2}$
      example: '2026-01-01'
  schemas:
    UsageReport:
      type: object
      description: Usage statistics and analytics
      properties:
        period:
          type: string
          enum:
            - daily
            - weekly
            - monthly
            - yearly
          description: Report period
          example: monthly
        start_date:
          type: string
          format: date
          description: Period start date
          example: '2026-01-01'
        end_date:
          type: string
          format: date
          description: Period end date
          example: '2026-01-31'
        messages:
          type: object
          description: Message statistics by status
          properties:
            total:
              type: integer
              example: 12450
            delivered:
              type: integer
              example: 12100
            failed:
              type: integer
              example: 350
            delivery_rate:
              type: number
              description: Delivery success rate (percentage)
              example: 97.19
              minimum: 0
              maximum: 100
        by_route:
          type: object
          description: Statistics broken down by route
          properties:
            otp:
              type: integer
              example: 3200
            transactional:
              type: integer
              example: 7500
            promotional:
              type: integer
              example: 1750
        total_cost:
          type: number
          description: Total cost for the period
          example: 6225.5
        currency:
          type: string
          description: Currency code
          example: BDT
      required:
        - period
        - start_date
        - end_date
        - messages
    Error:
      type: object
      description: Standard error response with detailed information
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Error category for programmatic handling
              example: validation_error
            code:
              type: string
              description: Specific error code
              example: invalid_phone_number
            message:
              type: string
              description: Human-readable error message
              example: >-
                Phone number must be in international format without spaces or
                special characters
            param:
              type: string
              nullable: true
              description: Parameter that caused the error
              example: to
            request_id:
              type: string
              description: Unique request identifier for support and debugging
              example: req_abc123xyz
            doc_url:
              type: string
              description: Link to relevant documentation
              example: https://developer.hixbe.com/errors/invalid-phone-number
          required:
            - type
            - code
            - message
            - request_id
      required:
        - error
  responses:
    ValidationError:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: validation_error
              code: invalid_phone_number
              message: >-
                Phone number must be in international format (e.g.,
                8801712345678)
              param: to
              request_id: req_def456
              doc_url: https://developer.hixbe.com/phone-format
    Unauthorized:
      description: Authentication failed - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: authentication_error
              code: invalid_api_key
              message: >-
                Invalid API key provided. Check your API key at
                https://dashboard.hixbe.com/api-keys
              request_id: req_abc123
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIKEY
      description: >-
        Use your API key as a Bearer token. Format: `Authorization: Bearer
        sk_live_xxxxx`

````

## Related topics

- [Get business bandwidth usage](https://docs.xerobi.com/network-api/endpoint/get-business-bandwidth-usage.md)
- [Get consumer usage stats](https://docs.xerobi.com/network-api/endpoint/get-consumer-usage.md)
- [Get JSON Delta](https://docs.xerobi.com/rpki-api/endpoint/get-json-delta.md)
- [Comparison Report](https://docs.xerobi.com/speed-api/endpoint/comparison-report.md)
- [Xerobi Developer Documentation](https://docs.xerobi.com/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.