---
title: "Query own metered usage for an app"
url: "https://livepeer.pymthouse.com/apis/clearinghouse-usage/versions/295ecb35-5fcc-474e-a596-7431f5a1e8aa/paths/api-v1-apps-clientId--usage/get"
---

> Full API specification: https://livepeer.pymthouse.com/apis/clearinghouse-usage/versions/295ecb35-5fcc-474e-a596-7431f5a1e8aa.md

# Query own metered usage for an app

`GET` `/api/v1/apps/{clientId}/usage`

Returns OpenMeter rows for the authenticated actor only. Authenticate with Bearer Auth0 user JWT (via Kong Gateway or Railway) or sk_* API key (Railway direct only). Path clientId must match the credential app. Optional externalUserId must equal the actor when set. Meters and groupBy dimensions are constrained to the provisioned catalog.

## Path parameters

- `clientId` (string, required)

## Query parameters

- `meter` (string, required)
- `externalUserId` (string, optional) - Optional. When set must equal the authenticated actor.
- `from` (string, date-time, optional)
- `to` (string, date-time, optional)
- `groupBy` (array, optional) - Extra catalog dimensions. client_id and external_user_id are always included server-side.

## Responses

- `200` - Actor-scoped usage rows
- `400` - Invalid meter, groupBy, time window, or externalUserId
- `401` - Missing or invalid Bearer credentials (including M2M Basic)
- `404` - Path clientId does not match the credential app
- `502` - Metering backend unavailable
- `503` - Metering backend not configured

## OpenAPI definition

```yaml
openapi: 3.1.0
info:
  title: Clearinghouse Builder API
  version: 1.0.1
servers:
  - url: https://builder-api-production-82bf.up.railway.app
    description: Railway builder-api (Auth0 JWT or sk_*; default until Kong Gateway
      is linked)
  - url: http://localhost:8095
    description: Local builder-api
  - url: ${KONNECT_PROXY_URL}
    description: Kong Gateway proxy (Auth0 JWT / DCR Bearer only; sk_* not accepted
      at the edge)
paths:
  /api/v1/apps/{clientId}/usage:
    get:
      summary: Query own metered usage for an app
      description: Returns OpenMeter rows for the authenticated actor only.
        Authenticate with Bearer Auth0 user JWT (via Kong Gateway or Railway) or
        sk_* API key (Railway direct only). Path clientId must match the
        credential app. Optional externalUserId must equal the actor when set.
        Meters and groupBy dimensions are constrained to the provisioned
        catalog.
      security:
        - userBearer: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
        - name: meter
          in: query
          required: true
          schema:
            type: string
            enum:
              - network_fee_usd_micros
              - billable_usd_micros
              - signed_ticket_count
              - fee_wei
              - billable_secs
              - network_fee_usd_micros_by_manifest
        - name: externalUserId
          in: query
          description: Optional. When set must equal the authenticated actor.
          schema:
            type: string
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
        - name: groupBy
          in: query
          description: Extra catalog dimensions. client_id and external_user_id are always
            included server-side.
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: Actor-scoped usage rows
        "400":
          description: Invalid meter, groupBy, time window, or externalUserId
        "401":
          description: Missing or invalid Bearer credentials (including M2M Basic)
        "404":
          description: Path clientId does not match the credential app
        "502":
          description: Metering backend unavailable
        "503":
          description: Metering backend not configured
security:
  - userBearer: []
components:
  securitySchemes:
    userBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT or sk_*
      description: Auth0 end-user access token (JWT) or end-user API key (sk_*).
        Gateway ($KONNECT_PROXY_URL) accepts Auth0 JWT / DCR Bearer only; sk_*
        works on Railway direct. Path clientId must match the credential's app
        client id.
```