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

# List usage events

> One usage event per billable job: `held` at submit, then `settled` (credits drawn for the measured length) or `voided` (nothing charged).



## OpenAPI

````yaml /openapi.json get /v1/usage
openapi: 3.1.0
info:
  title: Hooper API
  version: 1.0.0
  description: >-
    Submit basketball game video and receive highlights, shots and per-player
    box scores.


    All endpoints require `Authorization: Bearer hk_prod_…`. Money fields are
    integer **cents**. Timestamps are Unix seconds. Every list — top-level or
    embedded — is `{ object: "list", data, has_more, total_count }`.
servers:
  - url: https://api.hooper.gg
    description: Production (accepts hk_prod_ keys)
security:
  - apiKey: []
tags:
  - name: Uploads
    description: Resumable video uploads to Hooper storage.
  - name: Sessions
    description: >-
      A session is one submitted game and everything the pipeline produced for
      it.
  - name: Billing
    description: Prepaid credits, metered per second of video.
  - name: Webhooks
    description: Signed HTTP callbacks when a session finishes.
  - name: Events
    description: The log of every event Hooper has emitted for your organization.
paths:
  /v1/usage:
    get:
      tags:
        - Billing
      summary: List usage events
      description: >-
        One usage event per billable job: `held` at submit, then `settled`
        (credits drawn for the measured length) or `voided` (nothing charged).
      operationId: listUsage
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
        - name: status
          in: query
          schema:
            type: string
            enum:
              - held
              - settled
              - voided
        - name: api_key
          in: query
          schema:
            type: string
            example: key_11
        - name: created[gte]
          in: query
          schema:
            type: integer
            description: Unix seconds
        - name: created[lte]
          in: query
          schema:
            type: integer
            description: Unix seconds
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageEventList'
components:
  parameters:
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    StartingAfter:
      name: starting_after
      in: query
      description: 'Cursor: the `id` of the last item on the previous page.'
      schema:
        type: string
  schemas:
    UsageEventList:
      allOf:
        - $ref: '#/components/schemas/ListEnvelope'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/UsageEvent'
    ListEnvelope:
      type: object
      required:
        - object
        - data
        - has_more
        - total_count
      properties:
        object:
          type: string
          const: list
        has_more:
          type: boolean
        total_count:
          type: integer
        url:
          type: string
          description: 'Embedded lists only: the endpoint that pages the full set.'
          example: /v1/sessions/sess_18234/highlights
    UsageEvent:
      type: object
      properties:
        id:
          type: string
          example: ue_91
        object:
          type: string
          const: usage_event
        created:
          type: integer
          nullable: true
        session:
          type: string
          example: sess_18234
        group:
          type: string
          nullable: true
        api_key:
          type: string
          nullable: true
          example: key_11
        sku:
          type: string
          example: video_processing
        status:
          type: string
          enum:
            - held
            - settled
            - voided
        run_version:
          type: integer
        held_seconds:
          type: integer
          description: The estimate at submit.
        quantity_seconds:
          type: integer
          description: The measured length once settled.
        rate_cents_per_hour:
          type: integer
        cost_cents:
          type: integer
        settled_at:
          type: integer
          nullable: true
        voided_at:
          type: integer
          nullable: true
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: hk_prod_… / hk_stg_…
      description: >-
        API key issued by Hooper for your organization. Keys are
        environment-tagged: `hk_prod_` keys work against production, `hk_stg_`
        keys against staging.

````