Skip to main content
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:
  1. Navigate to Settings > Billing and Usage
  2. Select the Granular Usage tab
  3. 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
  4. 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

ParameterTypeRequiredDescription
start_timedatetimeYesStart of the time range (ISO 8601 format)
end_timedatetimeYesEnd of the time range (must be after start_time)
workspace_idsarray of UUIDsYesFilter results to specific workspaces
group_bystringNoDimension 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 rangeAggregationStride
Less than 1 dayHourlyhours: 1
1-31 daysDailydays: 1
32-93 days (~3 months)Weeklydays: 7
94-366 days (~1 year)Monthlydays: 30
More than 366 daysYearlydays: 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")

​
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:
ColumnDescription
Time Bucket StartStart of the time bucket
Time Bucket EndEnd of the time bucket
Workspace IDUUID of the workspace (when grouping by workspace)
Workspace NameName of the workspace (when grouping by workspace)
Project IDUUID of the project (when grouping by project)
Project NameName of the project (when grouping by project)
User IDUUID of the user (when grouping by user)
User EmailEmail of the user (when grouping by user)
API Key Short KeyShort key identifier (when grouping by API key)
TracesNumber 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)

​
Grouping options

The group_by parameter determines how usage data is aggregated:
ValueDescriptionDimensions returned
workspaceGroup by workspaceworkspace_id, workspace_name
projectGroup by projectproject_id, project_name
userGroup by useruser_id, user_email
api_keyGroup by API keyapi_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.