orgs

Get Granular Usage

Changed on

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. When omitted, all workspaces the user can read are included (avoids enumerating every workspace id in the URL, which can exceed proxy header limits).

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

Request

  • Base URL
    https://api.smith.langchain.com
  • URL
    https://api.smith.langchain.com/api/v1/orgs/current/billing/granular-usage
  • Auth
    • API key in header X-API-Key
    • or API key in header X-Organization-Id
    • or HTTP bearer

Query parameters

start_timestring date-time required
end_timestring date-time required
workspace_idsstring[] nullable
group_by'user' | 'api_key' | 'project' | 'workspace' | 'trace_tier'

Dimensions for grouping granular usage data.

kind'traces' | 'langsmith_deployments'

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.

trace_tier'longlived' | 'shortlived'

Response

Successful Response

Changes

  • 1a8ee9358d81Revision changes
    • breaking

      the / response's property type changed from object to string for status

    • breaking

      removed the required property // from the response with the status

    • breaking

      removed the required property // from the response with the status

    • breaking

      removed the required property // from the response with the status

    • info

      added the new optional query request parameter kind

    • info

      added the new optional query request parameter trace_tier

    • info

      the query request parameter workspace_ids became optional

    • info

      added the new enum value trace_tier to the query request parameter group_by

    • info

      query request parameter workspace_ids list-of-types was widened by adding types null

    • info

      for the query request parameter workspace_ids, the type was generalized from array to no type

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property // to the response with the status