Client API Usage API

These endpoints provide client-admin visibility into API metering activity for a specific client workspace. They are intended for operational review inside admin tooling such as the GOFA B2B console.

note

These endpoints are for authenticated client-admin or GOFA-admin operators. They are not intended for end-user mobile or web app sessions.

Authentication

Send an admin-capable bearer token in the Authorization header.

Authorization Header

Authorization: Bearer <client_admin_token>

GET /api/client/[clientId]/api-usage/summary

Returns the selected month's route-level usage summary for the specified client.

Summary Query Parameters

Name	Type	Required	Description
month	string	No	Month in YYYY-MM format. Defaults to the current month.

Summary Response

• 200 OK: Returns request totals plus tracked route summaries for the selected month.
• 400 Bad Request: Missing clientId or invalid month format.
• 401/403 Unauthorized: Caller does not have admin access for the client.

Sample Response

{
  "clientId": "demo",
  "monthKey": "2026-05",
  "totals": {
    "totalRequests": 12,
    "successfulRequests": 10,
    "failedRequests": 2,
    "totalCreditsConsumed": 4
  },
  "activeRoutes": [
    {
      "routeKey": "lesson-plays.create",
      "method": "POST",
      "pathPattern": "/api/lesson-plays",
      "productName": "Lesson Plays API",
      "chargeMode": "billable",
      "totalRequests": 4,
      "successfulRequests": 4,
      "failedRequests": 0,
      "totalCreditsConsumed": 4,
      "lastRequestAt": "2026-05-12T07:04:37.000Z",
      "defaultCreditCost": 1,
      "successChargePolicy": "charge_on_2xx"
    }
  ],
  "trackedRoutes": []
}

GET /api/client/[clientId]/api-usage/events

Returns recent request-level usage records for the selected month.

Events Query Parameters

Name	Type	Required	Description
month	string	No	Month in YYYY-MM format. Defaults to the current month.
limit	integer	No	Number of recent records to return. Range: 1-200. Default: 100.

Events Response

• 200 OK: Returns recent request records for the selected client and month.
• 400 Bad Request: Missing clientId, invalid month, or invalid limit.
• 401/403 Unauthorized: Caller does not have admin access for the client.

Sample Response

{
  "clientId": "demo",
  "monthKey": "2026-05",
  "limit": 100,
  "total": 2,
  "events": [
    {
      "eventId": "abc123",
      "clientId": "demo",
      "callerClientId": "demo",
      "apiKeyId": "key_live_demo",
      "tokenType": "client_token",
      "routeKey": "lesson-plays.create",
      "productId": "lesson_plays",
      "productName": "Lesson Plays API",
      "method": "POST",
      "pathPattern": "/api/lesson-plays",
      "environment": "sandbox",
      "chargeMode": "billable",
      "billableUnit": "successful_action",
      "successChargePolicy": "charge_on_2xx",
      "responseStatus": 200,
      "success": true,
      "creditsConsumed": 1,
      "requestSummary": {
        "userId": "user_123",
        "userDisplayNameSnapshot": "陳大文",
        "lessonId": "lesson_demo_001",
        "lessonNameSnapshot": "Chair Mobility Flow",
        "planPlayId": "plan_play_789"
      },
      "resultSummary": {
        "lessonPlayId": "lesson_play_456"
      },
      "occurredAt": "2026-05-12T07:04:37.000Z",
      "dayKey": "2026-05-12",
      "monthKey": "2026-05"
    }
  ]
}

Trace Fields

For billable activity routes, event records may include a small trace payload so operators can connect a charged request back to the domain action that happened.

Field	Description
requestSummary.userId	Effective target user for the request when available.
requestSummary.userDisplayNameSnapshot	Canonical user display-name snapshot captured at request time when the target user record is available.
requestSummary.lessonId	Requested lesson identifier for lesson-plays.create.
requestSummary.lessonNameSnapshot	Human-readable lesson-title snapshot captured at request time for operator review.
requestSummary.planPlayId	Related plan-play identifier when the lesson play was started from a plan.
resultSummary.lessonPlayId	The lesson-play record created by a successful lesson-plays.create call.

note

These trace fields are intentionally limited to billing-relevant identifiers plus a small set of human-readable snapshots for operator review. The API does not mirror the raw request body into usage logs.