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

# Get usage analytics

> Return a time-bucketed run series plus a per-definition top-N volume table for the caller's account over `[from, to)`. Bucket size is set by `granularity` (`hour`|`day`|`week`); bucket timestamps are UTC. The range is clamped server-side per granularity — an out-of-range or inverted span returns 400 before any aggregation runs. Success rates are derivable client-side from the per-bucket and per-definition counts.



## OpenAPI

````yaml /openapi.json get /usage
openapi: 3.1.0
info:
  title: GetDialed Flows API
  version: 0.1.0
servers:
  - url: https://api.getdialed.ai/flows
    description: Production
security: []
paths:
  /usage:
    get:
      tags:
        - usage
      summary: Get usage analytics
      description: >-
        Return a time-bucketed run series plus a per-definition top-N volume
        table for the caller's account over `[from, to)`. Bucket size is set by
        `granularity` (`hour`|`day`|`week`); bucket timestamps are UTC. The
        range is clamped server-side per granularity — an out-of-range or
        inverted span returns 400 before any aggregation runs. Success rates are
        derivable client-side from the per-bucket and per-definition counts.
      operationId: get_usage_usage_get
      parameters:
        - name: from
          in: query
          required: true
          schema:
            type: string
            format: date-time
            description: Range start (inclusive).
            title: From
          description: Range start (inclusive).
        - name: to
          in: query
          required: true
          schema:
            type: string
            format: date-time
            description: Range end (exclusive).
            title: To
          description: Range end (exclusive).
        - name: granularity
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/UsageGranularity'
            description: Time-bucket size.
            default: day
          description: Time-bucket size.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '400':
          description: >-
            The `from`/`to` range is invalid (`from` >= `to`) or exceeds the
            per-granularity span cap — rejected before any aggregation runs
            (D-10)
          content:
            application/json:
              example:
                detail: >-
                  Requested range exceeds the maximum span for granularity
                  'hour' (7 days)
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              example:
                detail: Authentication required
        '422':
          description: Validation error (see body for field details)
          content:
            application/json:
              example:
                detail: Validation error
        '429':
          description: Rate limit exceeded — retry after the Retry-After header
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
          content:
            application/json:
              example:
                detail: 'Rate limit exceeded: 100 per 1 minute'
      security:
        - APIKeyHeader: []
        - HTTPBearer: []
components:
  schemas:
    UsageGranularity:
      type: string
      enum:
        - hour
        - day
        - week
      title: UsageGranularity
      description: Time-bucket size for the usage series.
    UsageResponse:
      properties:
        series:
          items:
            $ref: '#/components/schemas/UsageBucket'
          type: array
          title: Series
          description: Per-bucket run counts over the requested range, oldest first.
        top_definitions:
          items:
            $ref: '#/components/schemas/DefinitionVolume'
          type: array
          title: Top Definitions
          description: Top definitions by run count in the range (~top 20).
      type: object
      required:
        - series
        - top_definitions
      title: UsageResponse
      description: 'The usage/analytics payload: time series + per-definition top-N table.'
      example:
        series:
          - bucket: '2026-07-09T00:00:00Z'
            failed: 2
            succeeded: 40
            total: 42
        top_definitions:
          - definition_id: def_a1b2c3d4
            succeeded: 124
            total: 128
    UsageBucket:
      properties:
        bucket:
          type: string
          format: date-time
          title: Bucket
          description: The bucket's start time (UTC).
        total:
          type: integer
          title: Total
          description: Total batches created in the bucket.
        succeeded:
          type: integer
          title: Succeeded
          description: Batches that completed successfully.
        failed:
          type: integer
          title: Failed
          description: Batches that failed or partially failed in the bucket.
      type: object
      required:
        - bucket
        - total
        - succeeded
        - failed
      title: UsageBucket
      description: One time bucket of run activity (UTC bucket key).
    DefinitionVolume:
      properties:
        definition_id:
          type: string
          title: Definition Id
          description: The definition id.
        total:
          type: integer
          title: Total
          description: Total batches the definition produced in range.
        succeeded:
          type: integer
          title: Succeeded
          description: Successful batches (success rate derivable client-side).
      type: object
      required:
        - definition_id
        - total
        - succeeded
      title: DefinitionVolume
      description: Per-definition run volume within the requested range (top-N table).
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    HTTPBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````