Granular billable usage

For LangSmith Cloud, granular billable usage data collection started on January 5, 2026. Data is not available for usage before this date.For self-hosted instances, data collection begins when the feature is enabled via the following environment variables, or after upgrading to a version with it enabled by default.

DEFAULT_ORG_FEATURE_ENABLE_GRANULAR_USAGE_REPORTING=true
GRANULAR_USAGE_TABLE_ENABLED=true

LangSmith provides granular billable usage APIs that allow you to retrieve detailed trace usage data broken down by workspace, project, user, or API key. This enables you to:

Track usage across different teams or workspaces
Identify which users or API keys are consuming the most traces
Analyze usage patterns over time
Export usage data for internal reporting

Prerequisites

You must have the organization:read permission to access granular usage data.
You can only view usage for workspaces you have read access to.

View in the UI

You can also view granular usage data in the LangSmith UI:

Navigate to Settings > Billing and Usage
Select the Granular Usage tab
Use the controls to:
- Select a time range:
  - Last 7 days, 30 days, 3 months, 6 months, 1 year, or custom
- Choose aggregation level (daily, weekly, or monthly)
- Group by workspace, project, user, or API key
- Filter to specific workspaces
Click Export CSV to download the data

API endpoints

Get granular usage data

Retrieve granular usage data with flexible grouping options.

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

Query parameters

Parameter	Type	Required	Description
`start_time`	datetime	Yes	Start of the time range (ISO 8601 format)
`end_time`	datetime	Yes	End of the time range (must be after start_time)
`workspace_ids`	array of UUIDs	Yes	Filter results to specific workspaces
`group_by`	string	No	Dimension to group by. One of: `workspace`, `project`, `user`, `api_key`. Default: `workspace`

Response

{
  "stride": {
    "days": 1,
    "hours": 0
  },
  "usage": [
    {
      "time_bucket": "2026-01-15T00:00:00Z",
      "dimensions": {
        "workspace_id": "uuid",
        "workspace_name": "My Workspace"
      },
      "traces": 1500
    }
  ]
}

The stride field indicates the time bucket size used for aggregation, calculated based on the requested time range:

Time range	Aggregation	Stride
Less than 1 day	Hourly	`hours: 1`
1-31 days	Daily	`days: 1`
32-93 days (~3 months)	Weekly	`days: 7`
94-366 days (~1 year)	Monthly	`days: 30`
More than 366 days	Yearly	`days: 365`

Example: Get usage by workspace

import httpx
from datetime import datetime, timedelta, timezone

client = httpx.Client(
    base_url="https://api.smith.langchain.com",
    headers={"x-api-key": "<your-api-key>"}
)

end_time = datetime.now(timezone.utc)
start_time = end_time - timedelta(days=30)

response = client.get(
    "/api/v1/orgs/current/billing/granular-usage",
    params={
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
        "workspace_ids": ["<workspace-id>"],
        "group_by": "workspace"
    }
)

data = response.json()
for record in data["usage"]:
    print(f"{record['time_bucket']}: {record['traces']} traces")

const response = await fetch(
  `https://api.smith.langchain.com/api/v1/orgs/current/billing/granular-usage?` +
  new URLSearchParams({
    start_time: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
    end_time: new Date().toISOString(),
    workspace_ids: "<workspace-id>",
    group_by: "workspace"
  }),
  {
    headers: {
      "x-api-key": "<your-api-key>"
    }
  }
);

const data = await response.json();
for (const record of data.usage) {
  console.log(`${record.time_bucket}: ${record.traces} traces`);
}

curl -X GET "https://api.smith.langchain.com/api/v1/orgs/current/billing/granular-usage?\
start_time=2026-01-01T00:00:00Z&\
end_time=2026-01-15T00:00:00Z&\
workspace_ids=<workspace-id>&\
group_by=workspace" \
  -H "x-api-key: <your-api-key>"

Example: Get usage by user

response = client.get(
    "/api/v1/orgs/current/billing/granular-usage",
    params={
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
        "workspace_ids": ["<workspace-id>"],
        "group_by": "user"
    }
)

data = response.json()
for record in data["usage"]:
    user_email = record["dimensions"].get("user_email", "Unknown")
    print(f"{user_email}: {record['traces']} traces")

Export usage as CSV

Export granular usage data as a downloadable CSV file.

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

This endpoint accepts the same query parameters as the granular usage endpoint and returns a CSV file. The CSV always includes all columns, but only the columns relevant to the selected group_by option are populated:

Column	Description
Time Bucket Start	Start of the time bucket
Time Bucket End	End of the time bucket
Workspace ID	UUID of the workspace (when grouping by workspace)
Workspace Name	Name of the workspace (when grouping by workspace)
Project ID	UUID of the project (when grouping by project)
Project Name	Name of the project (when grouping by project)
User ID	UUID of the user (when grouping by user)
User Email	Email of the user (when grouping by user)
API Key Short Key	Short key identifier (when grouping by API key)
Traces	Number of traces in the time bucket

Example: Export to CSV

response = client.get(
    "/api/v1/orgs/current/billing/granular-usage/export",
    params={
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
        "workspace_ids": ["<workspace-id>"],
        "group_by": "workspace"
    }
)

# Save to file
with open("usage_report.csv", "wb") as f:
    f.write(response.content)

curl -X GET "https://api.smith.langchain.com/api/v1/orgs/current/billing/granular-usage/export?\
start_time=2026-01-01T00:00:00Z&\
end_time=2026-01-15T00:00:00Z&\
workspace_ids=<workspace-id>&\
group_by=workspace" \
  -H "x-api-key: <your-api-key>" \
  -o usage_report.csv

Grouping options

The group_by parameter determines how usage data is aggregated:

Value	Description	Dimensions returned
`workspace`	Group by workspace	`workspace_id`, `workspace_name`
`project`	Group by project	`project_id`, `project_name`
`user`	Group by user	`user_id`, `user_email`
`api_key`	Group by API key	`api_key_short_key`

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Account administration

Tools

Additional resources

Prerequisites

View in the UI

API endpoints

Get granular usage data

Query parameters

Response

Example: Get usage by workspace

Example: Get usage by user

Export usage as CSV

Example: Export to CSV

Grouping options

​Prerequisites

​View in the UI

​API endpoints

​Get granular usage data

​Query parameters

​Response

​Example: Get usage by workspace

​Example: Get usage by user

​Export usage as CSV

​Example: Export to CSV

​Grouping options

​Related resources

Prerequisites

View in the UI

API endpoints

Get granular usage data

Query parameters

Response

Example: Get usage by workspace

Example: Get usage by user

Export usage as CSV

Example: Export to CSV

Grouping options

Related resources