API REFERENCE

Credit Usage Rollup (Admin)

On this page

GET/api/admins/credits/rollup

Returns the per-account rollup of credit usage over the selected period, sorted by total credits deducted descending. Each row carries the account identity (UUID + display name + primary email) and the aggregated spend so the admin dashboard can render a top-spenders table without joining client-side. Pair with GET /api/admins/credits/events?account_id=…&period=… to drill into the individual usage_events rows for a single account. Requires the authenticated account to be a Recoup admin.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/admins/credits/rollup' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Query parameters

periodstring · enum

Rollup window. daily = today (last 1 day), weekly = last 7 days, monthly = last 30 days, all = no cutoff (every event ever recorded). Defaults to monthly. Follows the existing admin period convention.

Values: "all", "daily", "weekly", "monthly"

Default: "monthly"

limitinteger

Page size — number of accounts to return per request, sorted by total credits deducted descending. Defaults to 100; max 500.

Default: 100

pageinteger

1-indexed page number. Server returns rows (page - 1) * limit through page * limit - 1. Defaults to 1. Use total_count in the response to drive a 'load more' control (page * limit < total_count).

Default: 1

Responses

200Credit usage rollup retrieved successfully

application/json

statusstring · enumrequired

Status of the request

Values: "success", "error"

periodstring · enumrequired

The period the response was computed over (echoes the request)

Values: "all", "daily", "weekly", "monthly"

pageintegerrequired

1-indexed page returned (echoes the request, or 1 if omitted)

minimum: 1

limitintegerrequired

Page size used for this response (echoes the request, or the default if omitted)

minimum: 1

total_countintegerrequired

Total number of distinct accounts with at least one usage_events row in the selected period (i.e. the size of the full result set before pagination). The client derives has_more as page * limit < total_count and shows 'X of Y accounts'. Computed via a COUNT(DISTINCT account_id) query alongside the paginated row fetch.

minimum: 0

rowsarray<object>required

Per-account credit usage totals, sorted by total_credits_deducted descending

Item properties

account_idstringrequired

UUID of the account

format: uuid

account_namestringnullable

Display name from the accounts table; null if the account has no name set

account_emailstringnullable

Primary email from account_emails joined for human-readable rows; null if no email is on file

format: email

total_credits_deductedintegerrequired

Sum of usage_events.credits_deducted across every event for this account in the selected period, in micro-dollars (1,000,000 = $1.00)

event_countintegerrequired

Number of usage_events rows aggregated into this total

errorstring

Error message (only present if status is 'error')

400Invalid period or limit parameter

application/json

statusstring · enumrequired

Status of the request

Values: "error"

messagestringrequired

Error message describing what went wrong

401Unauthorized - missing or invalid credentials

No response body schema is specified.

403Forbidden - authenticated account is not a Recoup admin

No response body schema is specified.

500Internal server error while computing the rollup

application/json

statusstring · enumrequired

Status of the request

Values: "error"

messagestringrequired

Error message describing what went wrong

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download accounts.json

View operation source

json

{
  "description": "Returns the per-account rollup of credit usage over the selected period, sorted by total credits deducted descending. Each row carries the account identity (UUID + display name + primary email) and the aggregated spend so the admin dashboard can render a top-spenders table without joining client-side. Pair with [`GET /api/admins/credits/events?account_id=…&period=…`](/api-reference/admins/credits-events) to drill into the individual `usage_events` rows for a single account. Requires the authenticated account to be a Recoup admin.",
  "parameters": [
    {
      "name": "period",
      "in": "query",
      "required": false,
      "description": "Rollup window. `daily` = today (last 1 day), `weekly` = last 7 days, `monthly` = last 30 days, `all` = no cutoff (every event ever recorded). Defaults to `monthly`. Follows the existing admin period convention.",
      "schema": {
        "type": "string",
        "enum": [
          "all",
          "daily",
          "weekly",
          "monthly"
        ],
        "default": "monthly"
      }
    },
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Page size — number of accounts to return per request, sorted by total credits deducted descending. Defaults to 100; max 500.",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 500,
        "default": 100
      }
    },
    {
      "name": "page",
      "in": "query",
      "required": false,
      "description": "1-indexed page number. Server returns rows `(page - 1) * limit` through `page * limit - 1`. Defaults to 1. Use `total_count` in the response to drive a 'load more' control (`page * limit < total_count`).",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "default": 1
      }
    }
  ],
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "Credit usage rollup retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AdminCreditsRollupResponse"
          }
        }
      }
    },
    "400": {
      "description": "Invalid `period` or `limit` parameter",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid credentials"
    },
    "403": {
      "description": "Forbidden - authenticated account is not a Recoup admin"
    },
    "500": {
      "description": "Internal server error while computing the rollup",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountErrorResponse"
          }
        }
      }
    }
  }
}