Add a bulk API for user deployment limits and rolling usage

[valerydluski]

Name and Version

DIAL Core 0.47 (development branch, commit 31b38d72)

What is the problem this feature will solve?

Users need a single view of their token limits and current usage across deployments for daily, weekly, and monthly windows.

DIAL Core currently exposes:

GET /v1/deployments/{deployment_name}/limits

This endpoint returns LimitStats for one known deployment. A client that needs to display a user usage dashboard must:

1. Retrieve the list of deployments.
2. Send a separate limits request for every deployment.
3. Merge the responses on the client side.

This produces an N+1 request pattern and does not provide a way to efficiently discover deployments for which the caller already has stored usage.

DIAL Core already maintains caller-scoped rate-limit aggregates in ResourceTypes.LIMIT:

• Token and request usage is stored per deployment.
• Token usage has rolling minute, day, week, and month buckets.
• Cost usage is stored globally for the caller across all models.

These records contain rolling aggregates rather than raw request history, but they are sufficient for reporting usage for the requested windows.

What is the feature you are proposing to solve the problem?

Add an authenticated bulk endpoint, for example:

GET /v1/user/limits

The endpoint should return the effective limits and current rolling usage for the deployments available to the authenticated caller.

Example response:

{
  "deployments": [
    {
      "id": "gpt-4o",
      "tokenStats": {
        "day": {
          "total": 100000,
          "used": 42000
        },
        "week": {
          "total": 500000,
          "used": 180000
        },
        "month": {
          "total": 2000000,
          "used": 640000
        }
      }
    }
  ],
  "costStats": {
    "day": {
      "total": 100.0,
      "used": 14.5
    },
    "week": {
      "total": 500.0,
      "used": 82.3
    },
    "month": {
      "total": 2000.0,
      "used": 310.7
    }
  }
}

The exact response schema may reuse the existing LimitStats, ItemLimitStats, and CostItemLimitStats types.

Acceptance criteria

• The response is scoped to the authenticated initiator: a JWT user or an API-key project. The endpoint must not accept an arbitrary user identifier.
• Effective limits are resolved using the same role and default-role logic as the existing per-deployment endpoint.
• Day, week, and month usage follows the existing rolling-window semantics: 24 hours, 7 days, and 30 days.
• Each deployment entry contains both the effective limit and used token count for every supported window.
• Deployments with a finite configured limit but no usage are returned with used: 0.
• Deployments with persisted usage are discoverable without issuing one request per deployment.
• Only deployments currently accessible to the caller are returned; revoked or inaccessible deployment names must not be exposed.
• User-level cost limits are returned once at the top level because cost usage is currently aggregated across all models, rather than per deployment.
• Existing RateLimiter state is used as the source of truth. Analytics logs and transient per-trace TokenStatsTracker records must not be required.
• The endpoint and response schemas are documented in OpenAPI.
• Unit and API tests cover role resolution, empty usage, multiple deployments, access filtering, and rolling-window values.

Application usage that exists only in transient per-trace statistics is outside the persisted rate-limit history. Supporting such applications would require persistent aggregation before they can be included in this API.

What alternatives have you considered?

• Continue using GET /v1/deployments followed by GET /v1/deployments/{deployment_name}/limits for every deployment. This causes an N+1 request pattern and cannot efficiently identify only deployments with stored usage.
• Add user-specific usage fields to GET /v1/deployments. This would couple deployment discovery with rate-limit storage and make the general listing endpoint more expensive.
• Calculate usage from analytics or prompt logs. These logs may be external, disabled, or unavailable for secured requests, while Core already stores the rolling aggregates required for this feature.