List credit activity

​

Returns your organization's credit-activity feed, newest first: every movement on your credit ledger.

Per movement (kind):

  • allot credits were granted by a plan or promotion.
  • consume granted credits were drawn for usage.
  • overflow pay-as-you-go credits were drawn once granted credits ran out.
  • expire an unused grant lapsed.
  • revoke a grant was clawed back.

A consume or overflow movement carries a usage_kind (ai_usage or tm_usage) describing what the credits were spent on.

Filtering: narrow the feed with kind and/or usage_kind (for example ?kind=consume for granted-credit draws, or ?usage_kind=ai_usage for AI spend). Page with page and limit.

Permissions
Key type Accepted Permission required Notes
Org API key yes billing:read Key must be scoped to the org whose activity is read
Personal API key yes billing:read Requires X-Org-ID; caller needs a role granting billing:read
Error Codes
Code HTTP Description
credit.handler.identity_missing 401 An authenticated organization identity is required
credit.usage.invalid_filter 400 A kind or usage_kind filter value is not recognized
credit.usage.failed 500 Failed to list credit activity
Query Parameters
  • kind
    Type: stringenum

    Filter by movement kind

    values
    • allot
    • consume
    • overflow
    • expire
    • revoke
  • usage_kind
    Type: stringenum

    Filter by what the credits were spent on

    values
    • ai_usage
    • tm_usage
  • page
    Type: integer

    Page number (1-indexed, default 1)

  • limit
    Type: integer

    Items per page (default 20, max 100)

Responses
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/credits/usage
curl 'https://api.nametrust.com/credits/usage?kind=allot&usage_kind=ai_usage&page=1&limit=1'

{
  "object": "list",
  "items": [
    {
      "object": "credit_entry",
      "id": "cent_01h455vb4pex5vsknk084sn02q",
      "kind": "consume",
      "credits": -10,
      "usage_kind": "ai_usage",
      "usage_ref": "usage_01h455vb4pex5vsknk084sn02q",
      "created_at": "2026-06-01T10:00:00Z"
    }
  ],
  "pages": {
    "object": "cursor",
    "has_prev": true,
    "direction": "next",
    "cursor": "abc123",
    "next_cursor": "def456",
    "prev_cursor": "xyz789",
    "page": 2,
    "total_pages": 10,
    "total_items": 100,
    "limit": 20,
    "has_next": true
  }
}

Paginated credit-activity feed