List credit activity

​

Returns your organization's recent credit-activity feed, newest first: each movement on your credit ledger within the retention window. Movements older than the retention window (about 35 days) are pruned and no longer appear.

Per movement (kind):

  • grant credits were granted by a plan, a promotion, or Nametrust directly.
  • consume granted credits were drawn for usage.
  • billable 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 billable movement carries a usage_kind (ai_usage or tm_usage) describing what the credits were spent on.

Each movement carries an actor: the principal that drove it (a user, a guest visitor, or the system), with the user profile embedded when one applies.

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
    grantconsumebillableexpirerevoke
  • usage_kind
    Type: "ai_usage" or "tm_usage"enum

    Filter by what the credits were spent on

  • 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=grant&usage_kind=ai_usage'

{
  "object": "list",
  "items": [
    {
      "object": "credit_entry",
      "id": "cent_01h455vb4pex5vsknk084sn02q",
      "kind": "consume",
      "credits": -10,
      "usage_kind": "ai_usage",
      "usage_ref": "usage_01h455vb4pex5vsknk084sn02q",
      "actor": {
        "object": "actor",
        "kind": "user",
        "method": "session",
        "user": {
          "object": "user",
          "last_login_at": "2025-06-15T09:30:00Z",
          "last_active_at": "2025-06-15T09:30:00Z",
          "id": "user_01h455vb4pex5vsknk084sn02q",
          "email": "jane@acme.com",
          "first_name": "Jane",
          "last_name": "Doe",
          "avatar_url": "https://example.com/avatar.jpg",
          "mfa_enabled": true,
          "created_at": "2025-06-01T12:00:00Z",
          "updated_at": "2025-06-15T09:30:00Z"
        },
        "personal_key": {
          "object": "actor_personal_key",
          "id": "pkey_01h455vb4pex5vsknk084sn02q"
        },
        "org_key": {
          "object": "actor_org_key",
          "id": "okey_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