Granular billable usage ↗

langchain guide intermediate authentication cost-management workflows

Summary: Retrieve detailed trace usage data broken down by workspace, project, user, or API key.

Original Documentation

Documentation Index#
Fetch the complete documentation index at: https://docs.langchain.com/llms.txt Use this file to discover all available pages before exploring further.

Retrieve detailed trace usage data broken down by workspace, project, user, or API key.

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.

Link last verified June 7, 2026. View original ↗

Source: LangChain Docs

Link last verified: 2026-03-04