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.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

periodquery · string

limitquery · integer

pagequery · integer

cURL for this request

curl --request GET \
  --url 'https://recoup-api.vercel.app/api/admins/credits/rollup'

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"
          }
        }
      }
    }
  }
}