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

# Usage data

> Generate an hourly consumption report.



## OpenAPI

````yaml get /usage
openapi: 3.1.0
info:
  title: Massive
  description: The missing services for agent-first development.
  version: 1.0.0
servers:
  - url: https://render.joinmassive.com
security:
  - bearerAuth: []
paths:
  /usage:
    get:
      summary: Usage data
      description: Generate an hourly consumption report.
      parameters:
        - name: from
          description: >-
            The [ISO datetime](https://www.w3.org/TR/NOTE-datetime) to select
            data starting from, inclusively.
          schema:
            type: string
            format: date-time
            example: '2025-12-24T18:00:00-06:00'
          in: query
          required: true
        - name: to
          description: >-
            The [ISO datetime](https://www.w3.org/TR/NOTE-datetime) to select
            data up to, inclusively.
          schema:
            type: string
            format: date-time
            example: '2025-12-25T9:00:00-06:00'
          in: query
          required: true
        - name: email
          description: >-
            **[Whitelabelers only]** The (case-insensitive) email address of the
            user whose data to select; multiple addresses can be provided by
            repeating the key; data for all addresses is selected by default.
          schema:
            type: array
            items:
              type: string
              format: email
              example: user@example.com
          in: query
        - name: service
          description: >-
            The service to select data for; multiple services can be provided by
            repeating the key; data for all services is selected by default.
          schema:
            $ref: '#/components/schemas/Services'
          in: query
        - name: by
          description: The time unit to group the data by.
          schema:
            type: string
            enum:
              - hour
              - day (planned)
              - total
            default: total
            example: total
          in: query
      responses:
        '200':
          description: The hourly report.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    email:
                      description: The email address of the user whose data is selected.
                      type: string
                      format: email
                      example: user@example.com
                    from:
                      description: The ISO datetime of the first datapoint.
                      type: string
                      format: date-time
                      example: '2025-12-25T00:00:00+00:00'
                    to:
                      description: The ISO datetime of the last datapoint.
                      type: string
                      format: date-time
                      example: '2025-12-25T15:00:00+00:00'
                    service:
                      description: The service included in the data.
                      allOf:
                        - $ref: '#/components/schemas/Service'
                    result:
                      description: The type of result included in the data.
                      type: string
                      enum:
                        - success
                        - failure
                      example: success
                    calls:
                      description: The number of API calls of the service and result type.
                      type: integer
                      minimum: 1
                      example: 17208
                    meanSecs:
                      description: The average number of elapsed seconds of the API calls.
                      type: number
                      minimum: 0
                      example: 6.78
                  required:
                    - email
                    - from
                    - to
                    - service
                    - result
                    - calls
                    - meanSecs
        '401':
          $ref: '#/components/responses/authenticationError'
        '403':
          $ref: '#/components/responses/authorizationError'
        '422':
          $ref: '#/components/responses/paramsError'
        '429':
          $ref: '#/components/responses/throttlingError'
        '500':
          $ref: '#/components/responses/unknownError'
components:
  schemas:
    Services:
      summary: API services
      type: array
      items:
        $ref: '#/components/schemas/Service'
      minItems: 1
      example:
        - search
        - browser
    Service:
      summary: API service
      type: string
      enum:
        - search
        - browser
      example: browser
  responses:
    authenticationError:
      description: The authorization header was missing.
      content:
        text/plain:
          schema:
            type: string
            example: Authorization header must be provided
    authorizationError:
      description: The API token was invalid.
      content:
        text/plain:
          schema:
            type: string
            example: Valid API token must be provided
    paramsError:
      description: One or more parameters were invalid.
      content:
        text/plain:
          schema:
            type: string
            example: Character counts must be no more than 255
    throttlingError:
      description: The rate limit was exceeded.
      content:
        text/plain:
          schema:
            type: string
            example: Rate limit was exceeded; please retry in 180 seconds
    unknownError:
      description: An unknown error occurred.
      content:
        text/plain:
          schema:
            type: string
            example: Unknown error occurred
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````