---
title: "Tenant usage analytics"
method: GET
path: "/credits/analytics"
tags: ["Ledger"]
---

# Tenant usage analytics

`GET /credits/analytics`

## Request

- Base URL: `https://api.paywithlocus.com/api`
- URL: `https://api.paywithlocus.com/api/credits/analytics`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Exact database rollups over captured BURN debits. Accepts either the legacy days=7|30|90 form or an explicit half-open from/to window, optionally bucketed and narrowed to one spender and/or one provider. The prior comparison covers the same elapsed span as the current period, including today's partial UTC day, and is narrowed by the same filter so deltas stay like-for-like; top-ups, allocations, refunds, and open reservations are excluded. usageDrift is null when the optional detector read is temporarily unavailable.

## Query parameters

- `days` 7 | 30 | 90
- `from` string, date-time
- `to` string, date-time
- `bucket` 'hour' | 'day' | 'week' | 'month'
- `initiator` string
- `provider` string
- `endpoint` string
- `limit` integer

## Response `200`

Usage, cost, margin, service, and account rollups

- AnalyticsResponse
  - `success` unknown, required
  - `analytics` object, required
    - `days` 7 | 30 | 90 | null, nullable, required: Echo of the legacy form; null when the request used from/to.
    - `bucket` 'hour' | 'day' | 'week' | 'month', required
    - `filter` AnalyticsFilter, required: The filter the response was computed under, echoed back.
      - `initiator` object, nullable, required
        - `type` 'oauth_member' | 'end_user' | 'agent_connection' | 'customer' | 'credential' | 'unattributed', required
        - `id` string, nullable, required
      - `provider` string, nullable, required
      - `endpoint` string, nullable, required
    - `timezone` 'UTC', required
    - `periodStart` string, date-time, required
    - `periodEndExclusive` string, date-time, required
    - `priorPeriodStart` string, date-time, required
    - `priorPeriodEndExclusive` string, date-time, required
    - `summary` AnalyticsSummary, required
      - `usageUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `baseUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `marginUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `calls` integer, required
      - `activeUsers` integer, required
    - `priorSummary` AnalyticsSummary, required
      - `usageUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `baseUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `marginUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `calls` integer, required
      - `activeUsers` integer, required
    - `series` AnalyticsBucket[], required
      - `start` string, date-time, required: First instant of the bucket (UTC).
      - `usageUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `baseUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `marginUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `calls` integer, required
      - `activeUsers` integer, required
    - `daily` AnalyticsDay[], required: series relabelled by the UTC day of each bucket start; identical to series when bucket is day.
      - `date` string, date, required
      - `usageUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `baseUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `marginUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `calls` integer, required
      - `activeUsers` integer, required
    - `services` AnalyticsService[], required
      - `provider` string, required
      - `endpoint` string, nullable, required
      - `usageUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `baseUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `marginUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `calls` integer, required
      - `activeUsers` integer, required: Distinct END USERS. Pooled agents, API keys and members have no end user, so an endpoint driven only by those reports zero here.
      - `spenders` integer, required: Distinct spenders, the same population AnalyticsProvider.spenders counts.
    - `providers` AnalyticsProvider[], required
      - `provider` string, required
      - `spenders` integer, required: Distinct spenders who used the provider.
      - `endpoints` integer, required: Distinct endpoints used; a provider-level burn with no endpoint counts as one.
      - `usageUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `baseUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `marginUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `calls` integer, required
      - `activeUsers` integer, required
    - `users` AnalyticsUser[], required
      - `externalUserId` string, required: Case-sensitive immutable ID in the tenant namespace. Prefer an identity-provider subject, not an email address.
      - `usageUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `marginUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `calls` integer, required
    - `initiators` AnalyticsInitiator[], required
      - `type` 'oauth_member' | 'end_user' | 'agent_connection' | 'customer' | 'credential' | 'unattributed', required
      - `initiatorId` string, nullable, required
      - `label` string, required
      - `authMethod` string, nullable, required
      - `clients` string[], required
      - `usageUsdc` string, required
      - `marginUsdc` string, required
      - `calls` integer, required
      - `providers` integer, required: Distinct providers this spender used in the current window.
      - `source` string: Customer rows only: the product (attribution.source; '' when the charges carried none).
      - `customerId` string: Customer rows only: the tenant's own customer id. initiatorId is <URL-encoded source>/<customerId>.
      - `name` string, nullable: Customer rows only: the customer directory's name, null when unnamed. label is the name when there is one.
      - `url` string, nullable: Customer rows only: the directory's link for the customer.
      - `adminUrl` string, nullable: Customer rows only: the directory's link into the tenant's own admin for the customer.
    - `customerSources` AnalyticsCustomerSource[]: Spend per product over every customer burn in the window (not only the ranked ones), under the same filter.
      - `source` string, required
      - `customers` integer, required
      - `usageUsdc` string, required
      - `calls` integer, required
    - `usageDrift` UsageDriftAnalytics, required
      - `mode` 'shadow' | 'enabled', required
      - `attributionCoverageRequired` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `currentWindowDays` integer, required
      - `baselineWindowDays` integer, required
      - `collecting` integer, required
      - `active` UsageDriftDetection[], required
        - `id` string, uuid, required
        - `feature` string, required
        - `appVersion` string, nullable, required
        - `status` 'SHADOW' | 'ACTIVE' | 'RESOLVED', required
        - `severity` 'INFO' | 'WARNING' | 'CRITICAL', required
        - `mode` 'shadow' | 'enabled', required
        - `coverageRatio` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
        - `baselineSamples` integer, required
        - `currentSamples` integer, required
        - `requiredSamples` integer, required
        - `baseline` object, required
        - `current` object, required
        - `percentageChange` string, nullable, required
        - `adjustedPValue` string, nullable, required
        - `contributors` object, required
        - `firstSeenAt` string, date-time, nullable
        - `detectedAt` string, date-time, nullable
        - `resolvedAt` string, date-time, nullable
        - `lastEvaluatedAt` string, date-time, required
        - `ledgerFilterPath` string, required
        - `informational` unknown, required
      - `recentResolved` UsageDriftDetection[], required
        - `id` string, uuid, required
        - `feature` string, required
        - `appVersion` string, nullable, required
        - `status` 'SHADOW' | 'ACTIVE' | 'RESOLVED', required
        - `severity` 'INFO' | 'WARNING' | 'CRITICAL', required
        - `mode` 'shadow' | 'enabled', required
        - `coverageRatio` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
        - `baselineSamples` integer, required
        - `currentSamples` integer, required
        - `requiredSamples` integer, required
        - `baseline` object, required
        - `current` object, required
        - `percentageChange` string, nullable, required
        - `adjustedPValue` string, nullable, required
        - `contributors` object, required
        - `firstSeenAt` string, date-time, nullable
        - `detectedAt` string, date-time, nullable
        - `resolvedAt` string, date-time, nullable
        - `lastEvaluatedAt` string, date-time, required
        - `ledgerFilterPath` string, required
        - `informational` unknown, required

## Other responses

- `400`: Unsupported range

---

[API](https://skmtc.dev/paywithlocus/apis/locus-pro-api.md) - [All operations](https://skmtc.dev/paywithlocus/apis/locus-pro-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paywithlocus/apis/locus-pro-api/revisions/aab8fa5d6cef?raw)