Get Granular Usage

Get granular usage data with flexible grouping.

kind selects the billable usage domain:

• traces (default): trace counts.
• langsmith_deployments: LangSmith Deployment metrics (nodes executed, agent runs, agent uptime). The three Deployment fields are populated and traces is 0.

trace_tier (only meaningful for kind=traces) optionally restricts results to a single retention tier (longlived = extended retention, shortlived = standard retention). When group_by=trace_tier, results are split into one record per retention tier per time bucket.

workspace_ids filters results to the specified workspaces. Only workspaces the user has read access to are included.

GET /api/v1/orgs/current/billing/granular-usage

Error

A valid request URL is required to generate request examples

200

{
  "stride": {
    "days": 0,
    "hours": 0
  },
  "usage": [
    {
      "dimensions": {
        "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "user_email": "<string>",
        "api_key_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "api_key_short_key": "<string>",
        "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "project_name": "<string>",
        "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "workspace_name": "<string>"
      },
      "time_bucket": "2023-11-07T05:31:56Z",
      "traces": 0,
      "nodes_executed": 0,
      "agent_runs": 0,
      "agent_uptime_seconds": 0
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

API KeyOrganization IDBearer Auth

X-API-Key · string · header · required

Query Parameters

start_time · string<date-time> · required

end_time · string<date-time> · required

workspace_ids · string<uuid>[] · required

group_by · enum<string> · default: workspace

Dimensions for grouping granular usage data.

Available options: user, api_key, project, workspace, trace_tier

kind · enum<string> · default: traces

Which billable usage domain a granular-usage query targets.

• traces: trace counts.
• langsmith_deployments: LangSmith Deployment metrics (nodes executed, agent runs, agent uptime).

Default is traces for backward compatibility — existing callers of GET /granular-usage without a kind query param get the same response shape they always did.

Available options: traces, langsmith_deployments

trace_tier · enum<string> | null

Available options: longlived, shortlived

Response

200

application/json

Successful Response

Response for granular usage query.

stride · GranularUsageStride · object · required

Stride configuration for time bucketing - only ONE field should be non-zero.

Show child attributes

usage · GranularUsageRecord · object[] · required

Show child attributes