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

# 워크스페이스 사용량 조회

> 워크스페이스(`organization_id`)의 기간별 사용량과 비용을 사용 유형별로 집계해 조회합니다. 본인 워크스페이스나 직속 하위 워크스페이스를 조회할 수 있습니다. AI 통화와 상담사 통화, 웹 채팅, 채널 채팅, 카카오 상담톡 활성방, 코파일럿 답변, 개인정보 보호, 문자 발신·수신, 유닛 테스트와 시나리오 테스트 실행이 대상입니다. 요금이 계산된 사용량만 집계하므로 최근 사용량은 조금 늦게 반영될 수 있습니다. 정산 기간이 마감된 뒤 요금이 계산된 사용량은 여기에는 포함되지만 그 청구서에는 포함되지 않으므로, 기간 경계에서는 청구서 금액과 다를 수 있습니다. 구독료, 전화번호 회선료, 상담사 좌석료, 부가서비스 같은 월 고정 요금은 사용량이 아니므로 청구서 API에서 조회합니다. 기간은 `start_at_after` 이상 `start_at_before` 미만이며, 최대 31일입니다. `start_at_after`를 생략하면 `start_at_before` 직전 시각이 속한 정산 월(Asia/Seoul)의 시작 시각을 사용하므로, 둘 다 생략하면 이번 정산 월 시작부터 지금까지입니다. 응답은 실제 적용한 기간을 `start_at`과 `end_at`(이 시각 미포함)으로 반환합니다. 상위 워크스페이스는 `include_sub_organizations=true`로 직속 하위 워크스페이스의 사용량을 함께 집계할 수 있습니다. 하위 워크스페이스 요청에서는 이 값을 무시합니다.



## OpenAPI

````yaml /api-reference/v3/openapi.json get /organizations/{organization_id}/usage
openapi: 3.1.0
info:
  title: vox.ai API
  description: >
    vox.ai API v3


    ### v3 공개 계약 규칙


    - 인증은 `Authorization: Bearer <token>` 헤더를 사용합니다. 워크스페이스 API 키를 Bearer 토큰으로
    전달합니다.

    - 요청과 응답 필드는 기본적으로 `snake_case`를 사용합니다.

    - `agent.data`는 에이전트 레지스트리와 호환되어야 하므로 `callSettings`, `toolIds`,
    `builtInTools`, `presetDynamicVariables` 같은 camelCase 필드를 유지합니다.

    - `_at`으로 끝나는 타임스탬프는 unix milliseconds입니다. 일부 입력값은 호환성을 위해 10~11자리 unix
    seconds도 허용하고 milliseconds로 정규화합니다.

    - 대량 발신 통화 가능 시간은 분 단위 정수(`start_min` / `end_min`)를 사용합니다. 알림 스케줄은 `HH:MM`
    문자열(`start_time` / `end_time`)을 사용합니다.

    - 응답 객체 자신의 식별자는 `id`입니다. 다른 리소스를 참조하는 필드와 path parameter는 `agent_id`,
    `call_id`, `telephone_line_id`처럼 명시적인 이름을 사용합니다.

    - 실패 응답은 `{ "error": { "code", "message", "details" } }` 형태입니다. 가능한 경우
    `details.field`, `details.reason`, `details.allowed_values`를 함께 제공합니다.
  version: 3.0.0
servers:
  - url: https://client-api.tryvox.co/v3
    description: 운영
security: []
paths:
  /organizations/{organization_id}/usage:
    get:
      tags:
        - Organizations
      summary: 워크스페이스 사용량 조회
      description: >-
        워크스페이스(`organization_id`)의 기간별 사용량과 비용을 사용 유형별로 집계해 조회합니다. 본인 워크스페이스나 직속
        하위 워크스페이스를 조회할 수 있습니다. AI 통화와 상담사 통화, 웹 채팅, 채널 채팅, 카카오 상담톡 활성방, 코파일럿 답변,
        개인정보 보호, 문자 발신·수신, 유닛 테스트와 시나리오 테스트 실행이 대상입니다. 요금이 계산된 사용량만 집계하므로 최근
        사용량은 조금 늦게 반영될 수 있습니다. 정산 기간이 마감된 뒤 요금이 계산된 사용량은 여기에는 포함되지만 그 청구서에는 포함되지
        않으므로, 기간 경계에서는 청구서 금액과 다를 수 있습니다. 구독료, 전화번호 회선료, 상담사 좌석료, 부가서비스 같은 월 고정
        요금은 사용량이 아니므로 청구서 API에서 조회합니다. 기간은 `start_at_after` 이상 `start_at_before`
        미만이며, 최대 31일입니다. `start_at_after`를 생략하면 `start_at_before` 직전 시각이 속한 정산
        월(Asia/Seoul)의 시작 시각을 사용하므로, 둘 다 생략하면 이번 정산 월 시작부터 지금까지입니다. 응답은 실제 적용한
        기간을 `start_at`과 `end_at`(이 시각 미포함)으로 반환합니다. 상위 워크스페이스는
        `include_sub_organizations=true`로 직속 하위 워크스페이스의 사용량을 함께 집계할 수 있습니다. 하위
        워크스페이스 요청에서는 이 값을 무시합니다.
      operationId: getOrganizationUsage
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            type: string
            description: 조회할 워크스페이스 ID입니다(본인 또는 직속 하위 워크스페이스).
            title: Organization Id
          description: 조회할 워크스페이스 ID입니다(본인 또는 직속 하위 워크스페이스).
        - name: start_at_after
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: >-
              사용 시각 하한입니다(unix ms, 이 시각 이상). 사용 시각은 통화·테스트·채팅은 과금 기준 시각(통화 시작 시각
              등)이고, 문자는 발신·수신 시각입니다. 기본값은 `start_at_before` 직전 시각이 속한 월의 시작
              시각입니다. 정산 기간의 월 경계는 Asia/Seoul 기준입니다. 10~11자리 unix 초 입력도 허용하며 자동으로
              ms로 변환됩니다.
            title: Start At After
          description: >-
            사용 시각 하한입니다(unix ms, 이 시각 이상). 사용 시각은 통화·테스트·채팅은 과금 기준 시각(통화 시작 시각
            등)이고, 문자는 발신·수신 시각입니다. 기본값은 `start_at_before` 직전 시각이 속한 월의 시작 시각입니다.
            정산 기간의 월 경계는 Asia/Seoul 기준입니다. 10~11자리 unix 초 입력도 허용하며 자동으로 ms로
            변환됩니다.
        - name: start_at_before
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: >-
              사용 시각 상한입니다(unix ms, 이 시각 미만). 기본값은 현재 시각입니다. `start_at_after`와의
              간격은 최대 31일입니다. 통화 목록 같은 다른 목록 API의 `*_before`와 달리 이 시각은 포함하지 않으므로,
              연속된 기간을 조회할 때는 앞 기간의 `start_at_before`를 다음 기간의 `start_at_after`로
              그대로 씁니다. 10~11자리 unix 초 입력도 허용하며 자동으로 ms로 변환됩니다.
            title: Start At Before
          description: >-
            사용 시각 상한입니다(unix ms, 이 시각 미만). 기본값은 현재 시각입니다. `start_at_after`와의 간격은
            최대 31일입니다. 통화 목록 같은 다른 목록 API의 `*_before`와 달리 이 시각은 포함하지 않으므로, 연속된
            기간을 조회할 때는 앞 기간의 `start_at_before`를 다음 기간의 `start_at_after`로 그대로
            씁니다. 10~11자리 unix 초 입력도 허용하며 자동으로 ms로 변환됩니다.
        - name: group_by
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - day
                  - organization
              - type: 'null'
            description: >-
              묶음 기준입니다. `day`는 `timezone` 기준 날짜별로, `organization`은 워크스페이스별로
              나눕니다. 생략하면 기간 전체를 사용 유형별로만 묶습니다.
            title: Group By
          description: >-
            묶음 기준입니다. `day`는 `timezone` 기준 날짜별로, `organization`은 워크스페이스별로 나눕니다.
            생략하면 기간 전체를 사용 유형별로만 묶습니다.
        - name: timezone
          in: query
          required: false
          schema:
            type: string
            description: '`group_by=day`의 날짜 경계에 적용할 IANA timezone입니다.'
            default: Asia/Seoul
            title: Timezone
          description: '`group_by=day`의 날짜 경계에 적용할 IANA timezone입니다.'
        - name: include_sub_organizations
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              직속 하위 워크스페이스의 사용량을 함께 집계할지 여부입니다. 상위 워크스페이스만 사용할 수 있습니다. 하위 워크스페이스
              요청에서는 무시합니다.
            default: false
            title: Include Sub Organizations
          description: >-
            직속 하위 워크스페이스의 사용량을 함께 집계할지 여부입니다. 상위 워크스페이스만 사용할 수 있습니다. 하위 워크스페이스
            요청에서는 무시합니다.
      responses:
        '200':
          description: 성공 응답
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationUsageResponse'
        '400':
          description: 요청 검증 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validationError:
                  summary: 요청 검증 오류
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Request validation failed.
                      details:
                        field: name
                        reason: must not be blank
                INVALID_TIMEZONE:
                  summary: 잘못된 timezone
                  value:
                    error:
                      code: INVALID_TIMEZONE
                      message: 지원하지 않는 timezone입니다.
                      details:
                        timezone: Not/AZone
        '401':
          description: 인증이 필요합니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Bearer 토큰 누락 또는 오류
                  value:
                    error:
                      code: UNAUTHORIZED
                      message: Authentication is required.
                      details: {}
        '403':
          description: 권한이 없습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: 권한이 없습니다.
                  value:
                    error:
                      code: FORBIDDEN
                      message: Permission denied.
                      details: {}
        '404':
          description: 리소스를 찾을 수 없습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  summary: 리소스를 찾을 수 없습니다.
                  value:
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: Resource not found.
                      details:
                        resource: agent
        '409':
          description: 충돌이 발생했습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                conflict:
                  summary: 상태 충돌이 발생했습니다.
                  value:
                    error:
                      code: CONFLICT
                      message: The requested operation conflicts with current state.
                      details:
                        current_status: draft
        '429':
          description: >-
            요청 한도를 초과했습니다. API 키 트래픽은 기본값으로 워크스페이스당 초당 5회·분당 120회, Supabase JWT
            트래픽은 기본값으로 사용자당 초당 10회·분당 240회로 제한되며, 워크스페이스 대시보드에는 기본 분당 2,400회의
            백스톱 한도가 적용됩니다. 한도는 운영자가 조정할 수 있고, 초과한 버킷의 실제 한도와 윈도우는 429 응답의
            X-RateLimit-Limit·X-RateLimit-Window 헤더로 알려 줍니다. 개별 경로 자체 리미터가 만든
            429 응답에는 이 헤더가 없을 수 있습니다.
          headers:
            Retry-After:
              description: >-
                초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우가 초기화될 때까지 남은 시간입니다. 단위는
                초입니다. 개별 경로 자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다.
              schema:
                type: integer
                minimum: 1
            X-RateLimit-Limit:
              description: >-
                초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우의 최대 요청 수입니다. 개별 경로 자체
                리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다.
              schema:
                type: integer
                minimum: 1
            X-RateLimit-Window:
              description: >-
                초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우의 길이입니다. 단위는 초입니다. 개별 경로
                자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rateLimited:
                  summary: 요청 한도를 초과했습니다.
                  value:
                    error:
                      code: RATE_LIMIT_EXCEEDED
                      message: Too many requests.
                      details:
                        limit: 10
                        window_seconds: 1
                        scope: user
        '500':
          description: 서버 내부 오류가 발생했습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internalError:
                  summary: 서버 내부 오류가 발생했습니다.
                  value:
                    error:
                      code: INTERNAL_ERROR
                      message: Internal server error.
                      details: {}
        '503':
          description: 서비스를 일시적으로 사용할 수 없습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                serviceUnavailable:
                  summary: 서비스를 일시적으로 사용할 수 없습니다.
                  value:
                    error:
                      code: SERVICE_UNAVAILABLE
                      message: Service temporarily unavailable.
                      details: {}
      security:
        - BearerAuth: []
components:
  schemas:
    OrganizationUsageResponse:
      properties:
        organization_id:
          type: string
          title: Organization Id
          description: 요청한 워크스페이스 ID입니다.
        start_at:
          type: integer
          title: Start At
          description: 집계 기간 시작 시각입니다(unix ms, 이 시각 포함).
        end_at:
          type: integer
          title: End At
          description: 집계 기간 끝 시각입니다(unix ms, 이 시각 미포함). 실제 적용된 `start_at_before`와 같습니다.
        timezone:
          type: string
          title: Timezone
          description: '`group_by=day`의 날짜 경계에 적용한 IANA timezone 이름입니다. 예: `Asia/Seoul`.'
        group_by:
          anyOf:
            - type: string
              enum:
                - day
                - organization
            - type: 'null'
          title: Group By
          description: 요청한 묶음 기준입니다. 지정하지 않았으면 `null`입니다.
        total_cost:
          type: string
          title: Total Cost
          description: '`items`의 `cost.total_cost` 합계입니다(KRW 원 단위, 문자열).'
        items:
          items:
            $ref: '#/components/schemas/OrganizationUsageItemResponse'
          type: array
          title: Items
          description: 사용량 묶음 목록입니다. 사용량이 있는 유형만 포함됩니다.
      type: object
      required:
        - organization_id
        - start_at
        - end_at
        - timezone
        - group_by
        - total_cost
        - items
      title: OrganizationUsageResponse
      description: 기간 사용량과 비용 집계입니다.
    ErrorResponse:
      type: object
      required:
        - error
      title: ErrorResponse
      description: 모든 실패 응답에서 사용하는 v3 error envelope입니다.
      examples:
        - error:
            code: VALIDATION_ERROR
            message: Request validation failed.
            details:
              field: name
              reason: must not be blank
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: 오류 payload입니다.
    OrganizationUsageItemResponse:
      properties:
        date:
          anyOf:
            - type: string
            - type: 'null'
          title: Date
          description: >-
            `timezone` 기준 날짜입니다(YYYY-MM-DD). `group_by=day`일 때만 값이 있고 그 밖에는
            `null`입니다.
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
          description: 사용한 워크스페이스 ID입니다. `group_by=organization`일 때만 값이 있고 그 밖에는 `null`입니다.
        usage_type:
          type: string
          enum:
            - inbound_call
            - outbound_call
            - web_call
            - web_chat
            - operator_call
            - chat
            - chat_room
            - copilot
            - pii_masking
            - sms
            - sms_received
            - unit_test
            - scenario_test
          title: Usage Type
          description: >-
            사용 유형입니다. `inbound_call`은 AI 수신 통화, `outbound_call`은 AI 발신 통화,
            `web_call`은 웹 음성 통화, `web_chat`은 웹 채팅, `operator_call`은 상담사가 직접 건 발신
            통화, `chat`은 채널 채팅(API·위젯·SMS·카카오 등)의 AI 답변, `chat_room`은 카카오 상담톡
            활성방, `copilot`은 코파일럿 답변(무료량 초과분), `pii_masking`은 통화 개인정보(PII) 보호,
            `sms`는 발신 문자, `sms_received`는 수신 문자, `unit_test`는 유닛 테스트 실행,
            `scenario_test`는 시나리오 테스트 실행입니다. AI 통화를 상담사가 이어받은 구간의 요금은 그 통화의 유형에
            포함됩니다.
        count:
          type: integer
          title: Count
          description: >-
            건수입니다. 통화
            유형(`inbound_call`·`outbound_call`·`web_call`·`web_chat`·`operator_call`)은
            통화 수, `chat`은 과금된 메시지 수(답변 요금과 모델 사용료가 붙은 메시지), `chat_room`은 활성방 수,
            `copilot`은 과금된 답변 수, `pii_masking`은 보호를 적용한 통화 수,
            `sms`·`sms_received`는 문자 수, `unit_test`·`scenario_test`는 실행 수입니다.
        billed_quantity:
          anyOf:
            - type: integer
            - type: 'null'
          title: Billed Quantity
          description: >-
            과금 수량 합계입니다. 단위는 `billed_unit`입니다. 음성 통화 유형은 AI 통화 요금의 과금 초(과금 단위로
            올림), `operator_call`은 상담사 통화 요금의 과금 초, `web_chat`·`chat`은 답변 요금이 붙은
            답변 수, `copilot`은 답변 수, `sms`·`sms_received`는 문자 수, `unit_test`는 실행
            수, `scenario_test`는 기본료가 붙은 에이전트 메시지 수입니다.
            `chat_room`·`pii_masking`은 과금 수량을 따로 기록하지 않아 `null`입니다.
        billed_unit:
          anyOf:
            - type: string
              enum:
                - second
                - message
                - run
            - type: 'null'
          title: Billed Unit
          description: >-
            `billed_quantity`의 단위입니다.
            `inbound_call`·`outbound_call`·`web_call`·`operator_call`은 `second`,
            `web_chat`·`chat`·`sms`·`sms_received`·`scenario_test`·`copilot`은
            `message`, `unit_test`는 `run`, `chat_room`·`pii_masking`은 `null`입니다.
        cost:
          $ref: '#/components/schemas/OrganizationUsageCostResponse'
          description: 사용 비용입니다.
      type: object
      required:
        - date
        - organization_id
        - usage_type
        - count
        - billed_quantity
        - billed_unit
        - cost
      title: OrganizationUsageItemResponse
      description: (날짜, 워크스페이스, 사용 유형) 묶음 1개의 사용량과 비용입니다.
    ErrorDetail:
      type: object
      required:
        - code
        - message
        - details
      title: ErrorDetail
      description: 기계가 읽을 수 있는 v3 오류 상세 정보입니다.
      examples:
        - code: VALIDATION_ERROR
          message: Request validation failed.
          details:
            field: name
            reason: must not be blank
      properties:
        code:
          type: string
          title: Code
          description: 기계가 읽을 수 있는 오류 code입니다. message parsing 대신 이 값을 사용합니다.
          examples:
            - VALIDATION_ERROR
        message:
          type: string
          title: Message
          description: 사용자에게 표시할 수 있는 오류 메시지입니다. 프로그램 처리는 `code`를 사용합니다.
          examples:
            - Request validation failed.
        details:
          type: object
          title: Details
          additionalProperties: true
          description: 구조화된 context입니다. 주로 `field`, `reason`, `allowed_values`를 포함합니다.
    OrganizationUsageCostResponse:
      properties:
        total_cost:
          type: string
          title: Total Cost
          description: '총 비용입니다(KRW 원 단위). 소수점 정밀도 유지를 위해 문자열로 전달됩니다. 예: ''123.45''.'
        breakdown:
          anyOf:
            - $ref: '#/components/schemas/OrganizationUsageCostBreakdownResponse'
            - type: 'null'
          description: >-
            항목별 금액입니다. AI 통화
            유형(`inbound_call`·`outbound_call`·`web_call`·`web_chat`)에만 값이 있고 그
            밖의 유형은 `null`입니다.
      type: object
      required:
        - total_cost
        - breakdown
      title: OrganizationUsageCostResponse
      description: 사용 비용입니다.
    OrganizationUsageCostBreakdownResponse:
      properties:
        platform_fee:
          type: string
          title: Platform Fee
          description: >-
            AI 통화 요금 중 분당 요금입니다(KRW 원 단위, 문자열). 예: '22.00'. 웹 채팅(`web_chat`)은 답변
            요금입니다. 모델 사용료는 `model_fee`에 따로 있습니다.
        model_fee:
          type: string
          title: Model Fee
          description: 모델 사용료입니다(KRW 원 단위, 문자열).
        transfer_fee:
          type: string
          title: Transfer Fee
          description: 통화 전환 요금입니다(KRW 원 단위, 문자열).
        telecom_fee:
          type: string
          title: Telecom Fee
          description: 통신료입니다(KRW 원 단위, 문자열).
        attempt_fee:
          type: string
          title: Attempt Fee
          description: 발신 기본료입니다(KRW 원 단위, 문자열). 음성사서함·통화 실패 요금을 포함하고 발신 통화에만 붙습니다.
      type: object
      required:
        - platform_fee
        - model_fee
        - transfer_fee
        - telecom_fee
        - attempt_fee
      title: OrganizationUsageCostBreakdownResponse
      description: >-
        AI 통화 요금의 항목별 금액입니다. 상담사가 이어받은 구간의 요금은 제외하므로 항목 합이 `total_cost`보다 작을 수
        있습니다.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Organization API key
      description: '워크스페이스 API 키를 `Authorization: Bearer <token>` 형식으로 보냅니다.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.