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

# Get customer growth

> Returns the business customer growth trend: new and cumulative customer counts per interval bucket (UTC), plus a summary with the growth rate versus the immediately preceding period of equal length.




## OpenAPI

````yaml https://raw.githubusercontent.com/bushaHQ/openapi/refs/heads/main/openapi-spec.yaml get /v1/insights/customers/growth
openapi: 3.0.0
info:
  title: Busha API
  contact:
    email: developers@busha.co
  description: >
    ## Introduction

    The **Busha API** is designed to provide businesses with tools for
    borderless financial transactions and operations, enabling modern, global
    money management. It serves as the backbone for facilitating:

    - Creation and management of multi-currency balances

    - Retrieval of real-time cryptocurrency rates

    - Substantial data insights for business owners


    Whether you’re a product-driven fintech or a developer building
    integrations, this API significantly accelerates implementation while
    reducing financial complexities.

    For detailed guides on API integration, visit our [official
    documentation]().



    ## Authentication

    All API requests require a **Bearer Token** for authentication, passed in
    the `Authorization` header.

    Your authorization value is a base64 encoded value of your api key and your
    secret key.

    You can obtain API tokens via your Busha user or business account.
    Authentication is mandatory to ensure secure and authorized interactions
    with the API.

    The API keys from the dashboard provides a base64 encoding of the your
    authorization tokens.


    Your generated Key should look like this:

    `VURtNXhWcHueantkpaiewjo0S044MWsadfojienuoxRTiWDJaeWJaTGxxanZ3Ym10OU1RZnVWajVW=`


    Example Header:

    ``` curl

    Authorization: Bearer
    VURtNXhWcHueantkpaiewjo0S044MWsadfojienuoxRTiWDJaeWJaTGxxanZ3Ym10OU1RZnVWajVW=

    ```


    ## Error Handling

    #Standardized error responses ensure predictable interactions. Errors are
    detailed for easy debugging and understanding:

    | **Error Code** | **HTTP Status Code** | **Description** |

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

    | `bad_request` | 400 | Invalid input or malformed request |

    | `unauthorized` | 401 | Invalid or missing authentication |

    | `not_found` | 404 | Resource not found |

    | `service_unavailable` | 503 | Server error |


    Basic Error Example:

    ``` json

    {
      "error": {
        "name": "bad_request",
        "message": "Invalid input data"
      }
    }

    ```


    Schema Error Body Example:

    ``` json

    {
      "error": {
        "name": "bad_request",
        "message": "Invalid input data"
      },
      "schema": {
        "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
        "fix": "Ensure that the object being submitted, matches the schema correctly"
      }
    }

    ```


    Field Error Body Example:

    ``` json

    {
      "error": {
        "name": "bad_request",
        "message": "Invalid input data"
      },
      "fields": {
        "field1": [
          {
            "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
          },
        ],
        "field2": [
          {
            "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
          }
        ],
      }
    }

    ```


    ## Pagination

    Pagination uses cursors provided as:

    The API supports **cursor-based pagination** for endpoints with large
    datasets. Pagination uses a `next_cursor` and `previous_cursor` returned in
    the response.

    Example Response Format:

    ``` json

    {
      "current_entries_size": 10,
      "next_cursor": "base64_cursor_value",
      "previous_cursor": "base64_previous_cursor_value"
    }

    ```


    ## Rate Limiting

    Rate limits determine how many API calls can be made in a rolling minute.
    This ensures fair and optimized use of system resources.


    The rate limits allowed by each resource will be provided with the header:

    ```curl

    x-rate-limit 100

    ```

    If this header does not exist, then the rate limit is set at a default 100
    req/min


    Requests exceeding the allocated quota will receive a `429 Too Many
    Requests` response.


    ##  Common Parameters

    Common parameters enhance consistency across endpoints:
      | **Parameter Name** | **Location** | **Description** | **Example** |
      | --- | --- | --- | --- |
      | `X-BU-PROFILE-ID` | Header | User profile identifier | `BUS_qwejinoiuiqw93ejjw` |
      | `id` | Path | Unique NanoID identifier | `dpt_jweqafajsndiun34fd` |
      | `cursor` | Query | Pagination cursor | `base64_cursor_string` |

    #### Paginated Response Example
      ``` json
      {
        "status": "success",
        "message": "Data retrieved",
        "pagination": {
          "next_cursor": "value_for_next_page",
          "current_entries_size": 20
        },
        "data": [...]
      }
      ```
  version: 1.0.0
servers:
  - url: https://api.sandbox.busha.so
    description: Sandbox Environment
  - url: https://api.busha.io
    description: Production Environment
security: []
tags:
  - name: Balances
    description: Handles account balances across different currencies.
    x-displayName: Balances
  - name: Bills
    description: Lorem Ipsum
    x-displayName: Bills
  - name: Cards
    description: Lorem Ipsum
    x-displayName: Cards
  - name: Cashback
    description: Main tag for cashback service endpoints
    x-displayName: Cashback
  - name: Currencies
    description: >
      Endpoints to manage supported currencies, their properties, and network
      details.
    x-displayName: Currencies
  - name: Customers
    x-internal: false
    description: Handle customer requests and responses
    x-displayName: Customers
  - name: Files
    description: Provides APIs to handle files upload
    x-displayName: Files
  - name: Futures
    description: Futures account management
    x-displayName: Futures
  - name: Insights
    description: Business analytics insights endpoints
    x-displayName: Insights
  - name: Mandate
    x-displayName: Mandate
  - name: Miscellaneous
    description: Provides auxiliary APIs to complement and enhance other services.
    x-displayName: Miscellaneous
  - name: News
    description: News article endpoints
    x-displayName: News
  - name: Pairs
    description: Access trading pair information and rates
    x-displayName: Pairs
  - name: PaymentLinks
    description: Payment Links
    x-displayName: PaymentLinks
  - name: PaymentRequests
    description: Payment request
    x-displayName: PaymentRequests
  - name: Pledges
    description: Customer-authorized pledge lifecycle APIs
    x-displayName: Pledges
  - name: PriceAlerts
    description: Price alert management endpoints
    x-displayName: PriceAlerts
  - name: Quotes
    description: Handle quotes requests and responses
    x-displayName: Quotes
  - name: Recipients
    x-displayName: Recipients
  - name: Stocks
    x-displayName: Stocks
  - name: Transactions
    x-displayName: Transactions
  - name: Transfers
    x-displayName: Transfers
  - name: Widget
    description: Widget operations
    x-displayName: Widget
paths:
  /v1/insights/customers/growth:
    get:
      tags:
        - Insights
      summary: Get customer growth
      description: >
        Returns the business customer growth trend: new and cumulative customer
        counts per interval bucket (UTC), plus a summary with the growth rate
        versus the immediately preceding period of equal length.
      operationId: getCustomerGrowth
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/InsightsStartDateQueryParam'
        - $ref: '#/components/parameters/InsightsEndDateQueryParam'
        - $ref: '#/components/parameters/InsightsIntervalQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/CustomerGrowth'
        4XX:
          $ref: '#/components/responses/InsightsError4XX'
        5XX:
          $ref: '#/components/responses/InsightsError5XX'
      security:
        - Auth:
            - insights:read
            - api:read
components:
  parameters:
    ProfileHeader:
      in: header
      name: X-BU-PROFILE-ID
      required: false
      description: User profile header
      schema:
        type: string
        example: BUS_YOK8tp5Zga01qOKEsqp07
    InsightsStartDateQueryParam:
      name: start_date
      in: query
      required: false
      description: >-
        Start of the reporting range (inclusive, UTC). Defaults to 30 days
        before end_date.
      schema:
        type: string
        format: date
      example: '2026-06-15'
    InsightsEndDateQueryParam:
      name: end_date
      in: query
      required: false
      description: End of the reporting range (inclusive, UTC). Defaults to today.
      schema:
        type: string
        format: date
      example: '2026-07-15'
    InsightsIntervalQueryParam:
      name: interval
      in: query
      required: false
      description: Bucket size for the series. Defaults to day.
      schema:
        $ref: '#/components/schemas/InsightsInterval'
  schemas:
    BaseSchema:
      description: General response Values
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: string
          x-order: 1
          x-go-type: string
          enum:
            - success
            - error
          example: success
        message:
          type: string
          x-order: 2
          example: message for success
    CustomerGrowth:
      type: object
      description: Business customer growth trend.
      required:
        - start_date
        - end_date
        - interval
        - summary
        - series
      properties:
        start_date:
          type: string
          format: date
          example: '2026-06-15'
        end_date:
          type: string
          format: date
          example: '2026-07-15'
        interval:
          $ref: '#/components/schemas/InsightsInterval'
        summary:
          $ref: '#/components/schemas/CustomerGrowthSummary'
        series:
          type: array
          items:
            $ref: '#/components/schemas/CustomerGrowthPoint'
    InsightsInterval:
      type: string
      description: Time bucket size for insight series.
      enum:
        - day
        - week
        - month
      example: day
    CustomerGrowthSummary:
      type: object
      description: Customer totals for the reporting range.
      required:
        - total_customers
        - new_customers
      properties:
        total_customers:
          type: integer
          format: int64
          description: Total customers as at end_date.
          example: 100932
        new_customers:
          type: integer
          format: int64
          description: Customers added within the reporting range.
          example: 2340
        growth_rate:
          $ref: '#/components/schemas/NullableDecimal'
    CustomerGrowthPoint:
      type: object
      description: One time bucket of the customer growth series.
      required:
        - date
        - new_customers
        - cumulative_customers
      properties:
        date:
          type: string
          format: date
          description: Start of the bucket (UTC).
          example: '2026-06-15'
        new_customers:
          type: integer
          format: int64
          example: 12
        cumulative_customers:
          type: integer
          format: int64
          example: 98211
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - name
            - message
          properties:
            name:
              type: string
              x-order: 40
              example: bad_request
            message:
              type: string
              example: Invalid Request
        fields:
          type: object
        schema:
          type: array
          items:
            type: object
      example:
        error:
          name: bad_request
          message: Invalid Request
    NullableDecimal:
      type: string
      description: nullable decimal value
      example: '100'
      x-go-type: decimal.Decimal
      x-go-type-import:
        path: github.com/shopspring/decimal
        name: decimal
      nullable: true
  responses:
    InsightsError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    InsightsError5XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
  examples:
    DefaultError:
      description: Default error
      value:
        error:
          name: bad_request
          message: Invalid request
    NotFoundError:
      description: Not Found error
      value:
        error:
          name: resource_not_found
          message: Resource Not Found
    UnAuthorizedError:
      description: Unauthorized Error
      value:
        error:
          name: unauthorized
          message: Unauthorized request
    RequestValidationError:
      description: Request Validation error example
      value:
        error:
          name: request_validation
          message: Validation error
        fields:
          field1:
            - reason: One of target and source amount must be set
          field2:
            - reason: One of target and source amount must be set
    SchemaValidationError:
      description: Schema validation error example
      value:
        error:
          name: schema_validation
          message: Error Validating Requests
        schema:
          - reason: >-
              The request body is defined as an object. However, it does not
              meet the schema requirements of the specification
            fix: >-
              Ensure that the object being submitted, matches the schema
              correctly
            schema_validation_error:
              - 'minLength: got 3, want 12'
    InternalServerError:
      description: Internal Server Error
      value:
        error:
          name: internal_server_error
          message: Internal Server Error
    ServiceUnavailableError:
      description: Service Unavailable Error
      value:
        error:
          name: service_unavailable
          message: Service Unavailable
  securitySchemes:
    Auth:
      type: http
      scheme: bearer
      description: Bearer Authentication

````