세분화된 청구 가능 사용량

세분화된 청구 가능 사용량

워크스페이스, 프로젝트, 사용자, 또는 API 키별로 분류된 상세 트레이스 및 LangSmith Deployment 사용량 데이터를 가져와요.

참고: 트레이스 사용량: LangSmith 클라우드의 경우 세분화된 청구 가능 트레이스 데이터 수집은 2026년 1월 5일에 시작됐어요. 그 이전에 수집된 트레이스에 대해서는 데이터를 사용할 수 없어요.

셀프 호스팅 인스턴스의 경우, 다음 환경 변수를 통해 기능을 활성화하거나 기본 활성화된 버전으로 업그레이드한 후에 트레이스 데이터 수집이 시작돼요.

DEFAULT_ORG_FEATURE_ENABLE_GRANULAR_USAGE_REPORTING=true
GRANULAR_USAGE_TABLE_ENABLED=true

셀프 호스팅 버전 0.16.0부터 셀프 호스팅 배포에서는 장기 보존(long-lived) 트레이스 사용량을 더 이상 추적하지 않아요. 이러한 배포에서 Long-lived only 보존 필터는 항상 0건을 표시해요.

LangSmith Deployment 사용량은 별도의 데이터 소스를 사용해요. 자세한 내용은 LangSmith Deployment 섹션을 참고해요.

LangSmith는 워크스페이스, 프로젝트, 사용자 또는 API 키별로 분류된 상세 사용량 데이터를 가져올 수 있는 세분화된 청구 가능 사용량 API를 제공해요. 동일한 엔드포인트에서 kind 쿼리 파라미터로 선택되는 두 개의 청구 가능 도메인이 지원돼요:

• 트레이스 사용량 (kind=traces, 기본): 수집된 트레이스 수.
• LangSmith Deployment 사용량 (kind=langsmith_deployments): LangSmith Deployment에 대한 실행된 노드, 에이전트 런, 에이전트 업타임.

두 종류 모두 동일한 쿼리 파라미터(시간 범위, 워크스페이스 필터, 그룹화 차원)를 공유하고 동일한 시간 버킷 형식을 반환해요. 데이터 소스는 별개이므로 한 종류가 반환한 레코드는 다른 종류에 나타나지 않아요.

이러한 API를 사용해 다음을 할 수 있어요:

• 서로 다른 팀 또는 워크스페이스 간 사용량 추적.
• 어떤 사용자 또는 API 키가 가장 많은 트레이스를 소비하거나 에이전트를 실행하는지 식별.
• 시간에 따른 사용 패턴 분석.
• 내부 보고를 위한 사용량 데이터 내보내기.

출처: 문서

본문

사전 요구사항

• 세분화된 사용량 데이터에 접근하려면 organization:read 권한이 있어야 해요.
• 읽기 접근 권한이 있는 워크스페이스의 사용량만 볼 수 있어요.

UI에서 보기

LangSmith UI에서도 세분화된 사용량 데이터를 볼 수 있어요:

1. Settings > Billing and Usage로 이동해요.
2. Granular Usage 탭을 선택해요.
3. LangSmith Traces와 LangSmith Deployments 하위 탭을 전환해 각 도메인을 확인해요. 활성 하위 탭은 URL(?tab=traces 또는 ?tab=deployments)에 반영되므로 페이지를 북마크해 같은 보기로 이동할 수 있어요.
4. 컨트롤을 사용해:
   • 시간 범위 선택 (Last 7 days, 30 days, 3 months, 6 months, 1 year, 또는 custom)
   • 워크스페이스, 프로젝트, 사용자, 또는 API 키별 그룹화
   • 특정 워크스페이스로 필터링
   • LangSmith Traces 탭에서 보존 계층으로 선택적 필터링 (All Retention / Long-lived only / Short-lived only)
5. Export CSV를 클릭해 활성 탭의 데이터를 다운로드해요.

시간 범위와 워크스페이스 필터는 두 하위 탭에 걸쳐 공유되며, 탭을 전환해도 선택한 내용이 유지돼요. LangSmith Deployments 탭은 세 개의 지표가 서로 다른 단위를 사용하므로 세 개의 통계 카드(전체 실행 노드 수 / 전체 에이전트 런 수 / 전체 에이전트 업타임(초))와 지표별 차트 하나를 세로로 쌓아 표시해요.

쿼리 파라미터

세분화된 사용량 엔드포인트는 다음 쿼리 파라미터를 받아요:

일 단위 계약

사용량 데이터는 일 단위로 집계돼요. 엔드포인트는 API 계층에서 창을 일 단위로 정규화해요:

• start_time은 해당 일의 UTC 자정으로 내림돼요.
• end_time은 다음 UTC 자정으로 올림돼요(이미 자정이면 무변경).
• 요청된 창과 겹치는 어떤 하루라도 전체 포함돼요.

따라서 2026-01-01T12:00:00Z부터 2026-01-02T12:00:00Z까지의 24시간 창은 1월 1일과 1월 2일 전체 버킷에 대한 사용량을 반환해요.

Stride

각 응답의 stride 필드는 요청된 시간 범위에서 계산된 집계에 사용된 시간 버킷 크기를 나타내요. 일이 최소이며, 하루 미만의 창도 하루 단위로 버킷팅돼요.

호환성

kind=langsmith_deployments와 group_by=trace_tier를 함께 사용하면 400 Bad Request를 반환해요. 보존 계층은 트레이스에만 적용돼요.

API 엔드포인트

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

kind를 생략한 기존 호출자는 항상 그래왔던 것과 동일한 응답 형태로 트레이스 사용량을 계속 받아요.

트레이스 사용량 (kind=traces)

응답

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

예시: 워크스페이스별 트레이스 사용량 가져오기

```typescript TypeScript
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: ***

예시: 사용자별 트레이스 사용량을 장기 보존 전용으로 필터링해 가져오기

</CodeGroup>

### LangSmith Deployment 사용량 (`kind=langsmith_deployments`)

각 레코드는 세 가지 지표를 함께 담으므로 단일 가져오기로 전체 Deployment 보기를 지원해요.

> **참고:** **LangSmith Deployment 사용량**은 트레이스 사용량과 별도로 소싱되며, 배포 사용량의 전체 보존 기간 동안 사용할 수 있어요.
>
> 셀프 호스팅 인스턴스의 경우 Deployment 사용량 엔드포인트는 옵트인 방식이에요. 다음과 같이 활성화해요:
>
> ```env
> REMOTE_METRICS_ROLLUP_ENABLED=true
> ```
>
> 또는 기본 활성화된 LangSmith 버전으로 업그레이드해요(셀프 호스팅 [changelog](/langsmith/self-hosted-changelog) 참조).

#### 응답

```json
{
"stride": {
  "days": 1,
  "hours": 0
},
"usage": [
  {
    "time_bucket": "2026-01-15T00:00:00Z",
    "dimensions": {
      "workspace_id": "uuid",
      "workspace_name": "My Workspace"
    },
    "nodes_executed": 12500,
    "agent_runs": 320,
    "agent_uptime_seconds": 86400
  }
]
}

```typescript TypeScript
const response = await fetch(
  `https://api.smith.langchain.com/api/v1/orgs/current/billing/granular-usage?` +
  new URLSearchParams({
    kind: "langsmith_deployments",
    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.nodes_executed} nodes, ` +
    `${record.agent_runs} runs, ${record.agent_uptime_seconds}s uptime`
  );
}

curl -X GET "https://api.smith.langchain.com/api/v1/orgs/current/billing/granular-usage?\
kind=langsmith_deployments&\
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: ***

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

```bash cURL
curl -X GET "https://api.smith.langchain.com/api/v1/orgs/current/billing/granular-usage/export?\
kind=langsmith_deployments&\
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: *** \
  -o deployment_usage_report.csv