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

# List usage events

> Every call that spent API credits, newest first, for the last 90 days: when, which operation, how many credits, the resource, the client, the API key and the request id. Calls that cost nothing (errors, pending, empty results, free operations) are not listed. Free.

Cost: free.



## OpenAPI

````yaml /openapi.json get /v1/usage/events
openapi: 3.1.0
info:
  title: Alura API
  version: 1.0.0
  description: Etsy market research for scripts and AI assistants.
servers:
  - url: https://api.alura.io
security:
  - apiKey: []
paths:
  /v1/usage/events:
    get:
      summary: List usage events
      description: >-
        Every call that spent API credits, newest first, for the last 90 days:
        when, which operation, how many credits, the resource, the client, the
        API key and the request id. Calls that cost nothing (errors, pending,
        empty results, free operations) are not listed. Free.


        Cost: free.
      operationId: account.usage.events
      parameters:
        - name: from
          in: query
          required: false
          description: >-
            Earliest charge, inclusive: an ISO 8601 date or date-time. Default
            and limit: 90 days ago.
          schema:
            description: >-
              Earliest charge, inclusive: an ISO 8601 date or date-time. Default
              and limit: 90 days ago.
            anyOf:
              - type: string
                format: date
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
              - type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
        - name: to
          in: query
          required: false
          description: >-
            Latest charge, exclusive: an ISO 8601 date or date-time. Default:
            now.
          schema:
            description: >-
              Latest charge, exclusive: an ISO 8601 date or date-time. Default:
              now.
            anyOf:
              - type: string
                format: date
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
              - type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
        - name: operation
          in: query
          required: false
          description: Only this operation id (a key of `costs` in GET /v1/usage).
          schema:
            description: Only this operation id (a key of `costs` in GET /v1/usage).
            type: string
            maxLength: 100
        - name: client
          in: query
          required: false
          description: >-
            Only this client; `unknown` for charges whose client was not
            recorded.
          schema:
            description: >-
              Only this client; `unknown` for charges whose client was not
              recorded.
            type: string
            enum:
              - claude
              - chatgpt
              - cursor
              - script
              - other
              - unknown
        - name: key_id
          in: query
          required: false
          description: 'Only calls made with this API key: `key_...`.'
          schema:
            type: string
            minLength: 1
            maxLength: 64
            description: 'Only calls made with this API key: `key_...`.'
        - name: limit
          in: query
          required: false
          description: 'Page size: default 25, at most 100.'
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: cursor
          in: query
          required: false
          description: >-
            The `next_cursor` of the previous page. Bound to the query, the
            workspace and the key.
          schema:
            type: string
        - name: fields
          in: query
          required: false
          description: >-
            Comma-separated dotted paths to return; `id`, `object` and `as_of`
            always come back.
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            Request-Id:
              $ref: '#/components/headers/Request-Id'
            Alura-Credits-Cost:
              $ref: '#/components/headers/Alura-Credits-Cost'
            Alura-Credits-Remaining:
              $ref: '#/components/headers/Alura-Credits-Remaining'
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    const: list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        object:
                          type: string
                          const: usage_event
                        id:
                          type: string
                          description: '`evt_...`'
                        created_at:
                          type: string
                          description: When the charge was settled.
                        operation:
                          type: string
                        credits:
                          type: integer
                          minimum: 0
                        resource_id:
                          description: >-
                            The product, shop or keyword the call returned or
                            listed; null for searches and batches.
                          type:
                            - string
                            - 'null'
                        client:
                          anyOf:
                            - type: string
                              enum:
                                - claude
                                - chatgpt
                                - cursor
                                - script
                                - other
                            - type: 'null'
                          description: >-
                            The client that made the call; null when it was not
                            recorded.
                        key_id:
                          description: >-
                            The API key that made the call; null for an MCP
                            connection signed in with OAuth.
                          type:
                            - string
                            - 'null'
                        request_id:
                          type: string
                      required:
                        - object
                        - id
                        - created_at
                        - operation
                        - credits
                        - resource_id
                        - client
                        - key_id
                        - request_id
                      additionalProperties: false
                  has_more:
                    type: boolean
                  next_cursor:
                    type:
                      - string
                      - 'null'
                  total:
                    type: object
                    properties:
                      value:
                        type: integer
                      relation:
                        type: string
                        enum:
                          - eq
                          - gte
                    required:
                      - value
                      - relation
                    additionalProperties: false
                required:
                  - object
                  - data
                  - has_more
                  - next_cursor
                  - total
                additionalProperties: false
              example:
                object: list
                data:
                  - object: usage_event
                    id: evt_01JMOCK0000000000000000000
                    created_at: '2026-10-15T12:00:00.000Z'
                    operation: research.products.get
                    credits: 1
                    resource_id: '4524717183'
                    client: claude
                    key_id: null
                    request_id: req_01JMOCK0000000000000000000
                has_more: false
                next_cursor: null
                total:
                  value: 1
                  relation: eq
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '402':
          $ref: '#/components/responses/Problem402'
        '403':
          $ref: '#/components/responses/Problem403'
        '404':
          $ref: '#/components/responses/Problem404'
        '405':
          $ref: '#/components/responses/Problem405'
        '429':
          $ref: '#/components/responses/Problem429'
        '500':
          $ref: '#/components/responses/Problem500'
        '503':
          $ref: '#/components/responses/Problem503'
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl "https://api.alura.io/v1/usage/events" \
              -H "Authorization: Bearer $ALURA_API_KEY"
        - lang: typescript
          label: TypeScript
          source: |-
            const res = await fetch('https://api.alura.io/v1/usage/events', {
              headers: {
                Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
              },
            });
            console.log(await res.json());
        - lang: python
          label: Python
          source: |-
            import json
            import os
            import urllib.request

            request = urllib.request.Request(
                "https://api.alura.io/v1/usage/events",
                headers={
                    "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
                },
            )
            with urllib.request.urlopen(request) as response:
                print(json.load(response))
components:
  headers:
    Request-Id:
      description: '`req_` + ULID; quote it when reporting a problem.'
      schema:
        type: string
    Alura-Credits-Cost:
      description: API credits this call cost.
      schema:
        type: integer
    Alura-Credits-Remaining:
      description: >-
        API credits left in the workspace's monthly allowance, counting calls
        still in flight. Absent when it cannot be read right now.
      schema:
        type: integer
  responses:
    Problem400:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/invalid_request
            title: Invalid request
            status: 400
            code: invalid_request
            detail: Invalid request
            suggestion: Fix the request as the detail says, then send it again.
            retryable: false
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem401:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/unauthorized
            title: Unauthorized
            status: 401
            code: unauthorized
            detail: Unauthorized
            suggestion: 'Send a valid API key as `Authorization: Bearer alura_sk_...`.'
            retryable: false
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem402:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/credits_exhausted
            title: API credits exhausted
            status: 402
            code: credits_exhausted
            detail: API credits exhausted
            suggestion: Upgrade the plan or wait for the monthly reset.
            retryable: false
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem403:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/plan_required
            title: Plan required
            status: 403
            code: plan_required
            detail: Plan required
            suggestion: Upgrade the workspace plan to use this operation.
            retryable: false
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem404:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/not_found
            title: Not found
            status: 404
            code: not_found
            detail: Not found
            suggestion: Check the ID, or search for it first.
            retryable: false
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem405:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/method_not_allowed
            title: Method not allowed
            status: 405
            code: method_not_allowed
            detail: Method not allowed
            suggestion: Use one of the methods in the Allow header.
            retryable: false
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem429:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/rate_limited
            title: Rate limited
            status: 429
            code: rate_limited
            detail: Rate limited
            suggestion: Wait for Retry-After, then retry.
            retryable: true
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem500:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/internal_error
            title: Internal error
            status: 500
            code: internal_error
            detail: Internal error
            suggestion: Retry; if it keeps failing, report the request_id.
            retryable: true
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem503:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/credits_unavailable
            title: API credits unavailable
            status: 503
            code: credits_unavailable
            detail: API credits unavailable
            suggestion: Retry shortly.
            retryable: true
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
  schemas:
    Problem:
      type: object
      description: RFC 9457 problem details.
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        code:
          type: string
          description: A code from the error catalog; new codes may be added.
          x-extensible-enum:
            - invalid_request
            - unknown_parameter
            - invalid_cursor
            - cursor_window_exceeded
            - id_type_mismatch
            - invalid_keyword
            - unauthorized
            - credits_exhausted
            - plan_required
            - insufficient_scope
            - workspace_required
            - workspace_locked
            - browser_refused
            - role_required
            - impersonation_refused
            - recent_sign_in_required
            - not_found
            - not_found_on_etsy
            - shop_opted_out
            - method_not_allowed
            - conflict
            - key_limit_reached
            - idempotency_processing
            - unprocessable
            - rate_limited
            - throttled
            - daily_credit_cap_exceeded
            - credits_reserved
            - fetch_limit_reached
            - internal_error
            - upstream_unavailable
            - credits_unavailable
            - service_unavailable
            - fetch_unavailable
            - upstream_timeout
        detail:
          type: string
        suggestion:
          type: string
        retryable:
          type: boolean
        request_id:
          type: string
        upgrade_url:
          type: string
          format: uri
          description: 'credits_exhausted and plan_required: where to upgrade the plan.'
        credits_needed:
          type: integer
          description: 'API credit refusals: what the call needed.'
        credits_remaining:
          type: integer
          description: >-
            API credit refusals: what is left (of the month, or of the day for
            daily_credit_cap_exceeded).
        resets_at:
          type: string
          format: date-time
          description: >-
            credits_exhausted and daily_credit_cap_exceeded: when the limit
            resets.
      required:
        - type
        - title
        - status
        - code
        - detail
        - suggestion
        - retryable
        - request_id
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'An API key: `Authorization: Bearer alura_sk_...`.'

````

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