zelf.developers

Usage

What your brand has spent against its limits, per group and per window, for both direct requests and AI clients. Reading it consumes nothing.

Get Usage

GET/api/v1/usage/usage.retrieve

Live consumption for your brand, per group and per window.

Both sections come back however you call: api groups count requests made with an API key, mcp groups count the ones an AI client makes, and the two never share a counter. authenticated_as says which of them the current credentials spend.

A window appears only when a limit is configured for it, so a brand with no monthly limit has no monthly row. Ask an administrator to set one and it appears here with no further work.

reset_in counts down to the end of the current window, which starts on its first request rather than on the clock. Reading this consumes no quota.

Returns Usage

brand_idType: string

Brand these figures belong to.

authenticated_asType: string

api_key or mcp, whichever made this call. It decides which groups your calls are counted against.

scopesType: UsageScope[]

One entry per metered group. Both sections are returned whichever way you call.

Show child attributes
scopes[].scopeType: string

Identifier of the metered group.

scopes[].human_nameType: string

Name of the group, as an admin sees it.

scopes[].kindType: string

request counts calls; item counts rows returned.

scopes[].sectionType: string

Which product the group meters: api for direct requests, mcp for AI clients. The two never share a counter.

scopes[].windowsType: UsageWindow[]

Every window that has a limit configured.

Show child attributes
scopes[].windows[].windowType: string

Which window this is: rps, rpm, rph, rpd, rpmonth, or an item window.

scopes[].windows[].limitType: integer

Most that may be spent in this window.

scopes[].windows[].usedType: integer

Spent so far in this window.

scopes[].windows[].remainingType: integer

Still available in this window.

scopes[].windows[].reset_inType: integer

Seconds until the window resets. The window starts on its first request rather than on the clock, so this is what is left of it.

historyType: UsageHistory

What was actually spent, day by day, from the usage ledger.

Show child attributes
history.start_dateType: string(date)

First day covered.

history.end_dateType: string(date)

Last day covered.

history.daysType: UsageDay[]

One entry per day and source that saw usage, oldest first.

Show child attributes
history.days[].sourceType: string

api for direct requests, mcp for AI clients.

history.days[].generalType: integer

Every counted call that day.

history.days[].ai_analysisType: integer

Calls counted against the AI analysis group, creator vetting included.

history.days[].data_recordsType: integer

Calls counted against data records.

history.days[].data_records_itemsType: integer

Records those calls returned.

history.days[].dateType: string(date)

The day, in the brand's billing timezone.

Responses

Usage

brand_idType: string

Brand these figures belong to.

authenticated_asType: string

api_key or mcp, whichever made this call. It decides which groups your calls are counted against.

scopesType: UsageScope[]

One entry per metered group. Both sections are returned whichever way you call.

Show child attributes
scopes[].scopeType: string

Identifier of the metered group.

scopes[].human_nameType: string

Name of the group, as an admin sees it.

scopes[].kindType: string

request counts calls; item counts rows returned.

scopes[].sectionType: string

Which product the group meters: api for direct requests, mcp for AI clients. The two never share a counter.

scopes[].windowsType: UsageWindow[]

Every window that has a limit configured.

Show child attributes
scopes[].windows[].windowType: string

Which window this is: rps, rpm, rph, rpd, rpmonth, or an item window.

scopes[].windows[].limitType: integer

Most that may be spent in this window.

scopes[].windows[].usedType: integer

Spent so far in this window.

scopes[].windows[].remainingType: integer

Still available in this window.

scopes[].windows[].reset_inType: integer

Seconds until the window resets. The window starts on its first request rather than on the clock, so this is what is left of it.

historyType: UsageHistory

What was actually spent, day by day, from the usage ledger.

Show child attributes
history.start_dateType: string(date)

First day covered.

history.end_dateType: string(date)

Last day covered.

history.daysType: UsageDay[]

One entry per day and source that saw usage, oldest first.

Show child attributes
history.days[].sourceType: string

api for direct requests, mcp for AI clients.

history.days[].generalType: integer

Every counted call that day.

history.days[].ai_analysisType: integer

Calls counted against the AI analysis group, creator vetting included.

history.days[].data_recordsType: integer

Calls counted against data records.

history.days[].data_records_itemsType: integer

Records those calls returned.

history.days[].dateType: string(date)

The day, in the brand's billing timezone.

from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key="<your-api-key>")

result = client.usage.retrieve()
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "brand_id": "brd_Lw6ZZmNYhW0P9k0x",
      "authenticated_as": "api_key",
      "scopes": [
        {
          "scope": "global",
          "human_name": "General",
          "kind": "request",
          "section": "api",
          "windows": [
            {
              "window": "rps",
              "limit": 100,
              "used": 10,
              "remaining": 90,
              "reset_in": 1
            },
            {
              "window": "rph",
              "limit": 5000,
              "used": 500,
              "remaining": 4500,
              "reset_in": 1800
            },
            {
              "window": "rpd",
              "limit": 10000,
              "used": 1000,
              "remaining": 9000,
              "reset_in": 43200
            }
          ]
        },
        {
          "scope": "ai_analysis",
          "human_name": "AI Analysis",
          "kind": "request",
          "section": "api",
          "windows": [
            {
              "window": "rps",
              "limit": 10,
              "used": 1,
              "remaining": 9,
              "reset_in": 1
            },
            {
              "window": "rph",
              "limit": 1000,
              "used": 100,
              "remaining": 900,
              "reset_in": 1800
            },
            {
              "window": "rpd",
              "limit": 5000,
              "used": 500,
              "remaining": 4500,
              "reset_in": 43200
            }
          ]
        },
        {
          "scope": "data_records",
          "human_name": "Data Records",
          "kind": "item",
          "section": "api",
          "windows": [
            {
              "window": "items_per_month",
              "limit": 10000,
              "used": 1000,
              "remaining": 9000,
              "reset_in": 1296000
            }
          ]
        },
        {
          "scope": "mcp",
          "human_name": "General",
          "kind": "request",
          "section": "mcp",
          "windows": [
            {
              "window": "rps",
              "limit": 20,
              "used": 2,
              "remaining": 18,
              "reset_in": 1
            },
            {
              "window": "rph",
              "limit": 10000,
              "used": 1000,
              "remaining": 9000,
              "reset_in": 1800
            },
            {
              "window": "rpd",
              "limit": 25000,
              "used": 2500,
              "remaining": 22500,
              "reset_in": 43200
            }
          ]
        },
        {
          "scope": "mcp.ai_analysis",
          "human_name": "AI Analysis",
          "kind": "request",
          "section": "mcp",
          "windows": [
            {
              "window": "rps",
              "limit": 5,
              "used": 1,
              "remaining": 4,
              "reset_in": 1
            },
            {
              "window": "rph",
              "limit": 2500,
              "used": 250,
              "remaining": 2250,
              "reset_in": 1800
            },
            {
              "window": "rpd",
              "limit": 10000,
              "used": 1000,
              "remaining": 9000,
              "reset_in": 43200
            }
          ]
        },
        {
          "scope": "mcp.data_records",
          "human_name": "Data Records",
          "kind": "item",
          "section": "mcp",
          "windows": [
            {
              "window": "items_per_month",
              "limit": 10000,
              "used": 1000,
              "remaining": 9000,
              "reset_in": 1296000
            }
          ]
        }
      ],
      "history": {
        "start_date": "2026-05-01",
        "end_date": "2026-10-21",
        "days": [
          {
            "date": "2026-10-20",
            "source": "api",
            "general": 4820,
            "ai_analysis": 48,
            "data_records": 4772,
            "data_records_items": 143160
          },
          {
            "date": "2026-10-21",
            "source": "mcp",
            "general": 311,
            "ai_analysis": 4,
            "data_records": 307,
            "data_records_items": 9210
          }
        ]
      }
    }
  ],
  "item_count": 1,
  "page": 1,
  "next": null,
  "previous": null
}