Usage API - Qoder CN

The usage APIs provide member-level Credits usage details and summaries, with filters for dates, sources, operations, and model tiers. They also query organization shared packages, service account Credits packages, seat-month balance batches, and periodic seat-month consumption, with status and period filters and pagination.

Key features

Organization packages: List organization shared package details with pagination.
Service account packages: List dedicated Credits packages for service accounts in the organization, including binding, validity, total quota, cumulative usage, nominal remaining quota, and consumption applicability conditions.

List member usage events

GET /v1/organizations/{org_id}/members/{member_id}/usage-events

Query parameters:

Parameter	Type	Description
`startDate`	string	Optional; earliest event start time (inclusive); supports RFC 3339 format or Unix millisecond timestamp
`endDate`	string	Optional; latest event start time (inclusive); supports RFC 3339 format or Unix millisecond timestamp. When both dates are provided, the range must not exceed 7 days
`sources`	string	Filter by source, comma-separated
`operations`	string	Filter by operation type, comma-separated
`modelTiers`	string	Filter by model tier, comma-separated
`maxResults`	integer	Items per page; default 20, max 100
`nextToken`	string	Pagination cursor

Request example:

curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/members/member_001/usage-events?startDate=2025-01-01T00:00:00Z&endDate=2025-01-07T23:59:59Z&maxResults=20" \
  -H "Authorization: Bearer <api_key>"

Response example:

{
  "usages": [
    {
      "eventId": "019c1234-5678-7abc-8def-0123456789ab",
      "timestamp": 1736073000000,
      "beginAt": "2025-01-05T10:30:00Z",
      "finishAt": "2025-01-05T10:31:00.123Z",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "memberId": "member_001",
      "userEmail": "user@example.com",
      "source": "IDE",
      "operation": "Agent",
      "modelTier": "Standard",
      "credits": 1.5,
      "cost": 1.5
    }
  ],
  "maxResults": 20,
  "nextToken": "token_xyz"
}

Event identity and time fields (shared by member and organization usage events):

Field	Type	Description
`usages[].eventId`	string	Stable unique ID of the aggregated usage record
`usages[].timestamp`	int64	Start time (Unix millisecond timestamp)
`usages[].beginAt`	string	Usage event start time in UTC RFC 3339 format, preserving millisecond precision; represents the same instant as `timestamp`.
`usages[].finishAt`	string	Latest reported usage event finish time in UTC RFC 3339 format, preserving millisecond precision. Omitted when unavailable.

finishAt can advance as newer usage is reported for the same event. eventId and beginAt remain unchanged.

Get usage summary

GET /v1/organizations/{org_id}/members/{member_id}/usage-summary

Query parameters:

Parameter	Type	Description
`startDate`	string	Start date (ISO 8601)
`endDate`	string	End date (ISO 8601); range must not exceed 7 days
`groupBy`	string	Group by: `source` or `operation`

Request example:

curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/members/member_001/usage-summary?startDate=2025-01-10T00:00:00Z&endDate=2025-01-16T23:59:59Z&groupBy=source" \
  -H "Authorization: Bearer <api_key>"

Response example:

{
  "summary": {
    "IDE": 120.5,
    "Web": 30.0
  }
}

List organization usage events

GET /v1/organizations/{org_id}/usage-events

Query parameters are the same as the member usage events endpoint (startDate, endDate, sources, operations, modelTiers, maxResults, nextToken). Returns usage events across all members in the organization. Request example:

curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/usage-events?startDate=2025-01-01T00:00:00Z&endDate=2025-01-07T23:59:59Z" \
  -H "Authorization: Bearer <api_key>"

Response example:

{
  "usages": [
    {
      "eventId": "019c1234-5678-7abc-8def-0123456789ac",
      "timestamp": 1736073000000,
      "beginAt": "2025-01-05T10:30:00Z",
      "finishAt": "2025-01-05T10:31:00.123Z",
      "userId": "550e8400-e29b-41d4-a716-446655440005",
      "memberId": "member_005",
      "userEmail": "member5@example.com",
      "source": "IDE",
      "operation": "Inline Chat",
      "modelTier": "Premium",
      "credits": 5.0,
      "cost": 5.0
    }
  ],
  "maxResults": 20,
  "nextToken": "token_next"
}

List organization resource packages

Query total quota, cumulative usage, remaining quota, and validity periods for organization shared packages and service account Credits packages, for quota dashboards, billing reconciliation, and balance alerts.

Access requirements

Call the endpoints over HTTPS using the target organization’s Organization API Key:

Authorization: Bearer <ORGANIZATION_API_KEY>
Accept: application/json

The API key’s organization must match organization_id in the path. Both endpoints require an organization identity; personal and service account credentials cannot be used. Querying service account packages also requires the service account capability to be enabled for the organization. The examples use BASE_URL for the OpenAPI service URL. Use https://api.qoder.com.cn for this site, without a trailing /.

Method	Path	Scope
GET	`/v1/organizations/{organization_id}/resource-packages`	Organization shared packages
GET	`/v1/organizations/{organization_id}/service-accounts/resource-packages`	Service account Credits packages within the organization

Query the two package types separately. Responses contain package details, exclude personal packages, and do not include cross-package aggregate fields.

organization_id is a required string path parameter.
Responses are JSON with lowerCamelCase fields. Times are UTC RFC 3339 strings, such as 2027-09-01T00:00:00Z.
Quota fields are JSON numbers and can contain decimals. Preserve precision in calculations, storage, and display; do not round to integers.
Successful responses use HTTP 200 and Cache-Control: no-store. All statuses are queried by default; no matching packages returns an empty array.

Query organization shared packages

GET /v1/organizations/{organization_id}/resource-packages Query parameters

Parameter	Type	Required	Default	Description
`status`	string	No	No filter	`active`, `exhausted`, `expired`, `suspended`; case-insensitive
`orderBy`	string	No	`expiresAt`	`expiresAt`, `activatedAt`, `remainingValue`
`order`	string	No	`asc`	`asc` (ascending) or `desc` (descending); case-insensitive
`maxResults`	integer	No	20	Page size; recommended range 1–100. Values above 100 use 100; invalid values use 20
`nextToken`	string	No	None	Cursor from the previous response; omit on the first request

Ties are resolved by package ID in the direction specified by order. Results include expired, exhausted, and suspended packages by default; deleted packages are excluded. Request example

curl --get "${BASE_URL}/v1/organizations/${ORGANIZATION_ID}/resource-packages" \
  -H "Authorization: Bearer ${ORGANIZATION_API_KEY}" \
  -H 'Accept: application/json' \
  --data-urlencode 'status=active' \
  --data-urlencode 'orderBy=expiresAt' \
  --data-urlencode 'order=asc' \
  --data-urlencode 'maxResults=20'

Success response example

{
  "resourcePackages": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "name": "Organization Shared Credits Pack",
      "source": "purchased",
      "status": "active",
      "activatedAt": "2026-09-01T00:00:00Z",
      "expiresAt": "2027-09-01T00:00:00Z",
      "limitValue": 3000,
      "usedValue": 800.25,
      "remainingValue": 2199.75,
      "unit": "credits"
    }
  ],
  "maxResults": 20
}

Package fields

Field	Type	Description
`id`	string	Unique package identifier
`name`	string	Package name
`source`	string	Source; see the values below
`status`	string	Status; see “Status and usage semantics”
`activatedAt`	string	Activation time; omitted when unavailable
`expiresAt`	string	Expiration time
`limitValue`	number	Total package quota
`usedValue`	number	Cumulative package usage
`remainingValue`	number	Nominal remaining package quota
`unit`	string	Quota unit, such as `credits`; use the returned value

`source`	Meaning
`purchased`	Purchased
`bonus`	Promotional grant
`trial`	Trial
`carryOver`	Plan carryover
`refund`	Refund compensation grant; a package source, not a refund status
`dev`	Development use
`sales`	Sales use
`unknown`	Unrecognized source

Query service account packages

GET /v1/organizations/{organization_id}/service-accounts/resource-packages Query dedicated big_model_credits packages for service accounts in the organization. The unit is always credits. Query parameters

Parameter	Type	Required	Default	Description
`status`	string	No	No filter	`active`, `exhausted`, `expired`, `suspended`, `refunded`; case-insensitive
`maxResults`	integer	No	20	Page size; recommended range 1–100. Values above 100 use 100; invalid values use 20
`nextToken`	string	No	None	Cursor from the previous response; omit on the first request

Results are always sorted by expiration time, creation time, and package ID in ascending order. Custom sorting, time ranges, and filtering by an individual service account are not supported. Request example

curl --get "${BASE_URL}/v1/organizations/${ORGANIZATION_ID}/service-accounts/resource-packages" \
  -H "Authorization: Bearer ${ORGANIZATION_API_KEY}" \
  -H 'Accept: application/json' \
  --data-urlencode 'status=active' \
  --data-urlencode 'maxResults=20'

Success response example

{
  "resourcePackages": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "name": "Service Account Credits Pack",
      "targetId": "",
      "quotaKey": "big_model_credits",
      "status": "active",
      "createdAt": "2026-09-01T00:00:00Z",
      "expiresAt": "2027-09-01T00:00:00Z",
      "limitValue": 300000,
      "usedValue": 12.75,
      "remainingValue": 299987.25,
      "unit": "credits",
      "applicabilityConditions": []
    }
  ],
  "maxResults": 20
}

Package fields

Field	Type	Description
`id`	string	Unique package identifier
`name`	string	Package name
`targetId`	string	Empty string means service accounts in the organization share this dedicated package; otherwise, the bound service account ID
`quotaKey`	string	Always `big_model_credits`
`status`	string	Status; see “Status and usage semantics”
`createdAt`	string	Creation time
`expiresAt`	string	Expiration time
`limitValue`	number	Total package quota
`usedValue`	number	Cumulative package usage
`remainingValue`	number	Nominal remaining package quota, with a minimum of 0
`unit`	string	Always `credits`
`applicabilityConditions`	array	Consumption applicability conditions; an empty array imposes no dimension restrictions
`applicabilityConditions[].dimension`	string	Applicability dimension name, such as `model`
`applicabilityConditions[].allowedValues`	string[]	Allowed values or matching expressions for this dimension
`applicabilityConditions[].matchType`	string	`exact` for exact matching or `regex` for regular expressions; `unknown` if unrecognized

For a package with an empty targetId, cumulative usage is generated by all service accounts sharing the package; it is not the consumption of one account. Service account packages do not have source or activatedAt fields.

Status and usage semantics

Status	Shared packages	Service account packages	Meaning
`active`	Supported	Supported	Active; still subject to expiration and other consumption conditions
`exhausted`	Supported	Supported	Quota exhausted
`expired`	Supported	Supported	Expired
`suspended`	Supported	Supported	Suspended
`refunded`	Unsupported filter value	Supported	Refunded; further consumption stops, cumulative usage is retained
`unknown`	May be returned	May be returned	Unrecognized status; cannot be used as a query parameter

usedValue is cumulative consumption over the package lifetime, not daily usage, and does not reset with the organization’s subscription cycle. These endpoints do not break consumption down by day, member, or service account. remainingValue is nominal unconsumed quota, not a guarantee of current spendability. Expired, suspended, or refunded packages cannot be used even if a balance remains. Active packages are also subject to binding, applicability conditions, and budgets. Status updates may be delayed; check both status and expiresAt when determining validity. For balance alerts, filter by status=active, then check validity and applicability. For cross-package totals, fetch every page and ensure consistent units and scope. Cumulative usage can exceed the total quota; use the original returned values and do not cap usedValue at limitValue.

Pagination

Both endpoints use the same response structure:

Field	Type	Description
`resourcePackages`	array	Packages on the current page; `[]` when no records match
`maxResults`	integer	Actual page size used for this request
`nextToken`	string	Optional next-page cursor; absent or empty means the end

Omit nextToken on the first request.
If the response has a nonempty nextToken, pass it unchanged to the next request to the same endpoint.
Keep the organization, filters, sort parameters, and maxResults unchanged between pages.
Cursors are opaque server-generated strings; do not generate or parse them. URL-encode query parameters.
Pagination does not provide a snapshot across requests. Additions and status or usage changes during retrieval may affect results; restart the query to refresh the data.

Second-page request example:

curl --get "${BASE_URL}/v1/organizations/${ORGANIZATION_ID}/service-accounts/resource-packages" \
  -H "Authorization: Bearer ${ORGANIZATION_API_KEY}" \
  --data-urlencode 'status=active' \
  --data-urlencode 'maxResults=20' \
  --data-urlencode "nextToken=${NEXT_TOKEN}"

Response when no records match:

{
  "resourcePackages": [],
  "maxResults": 20
}

Error handling

Error responses contain requestId, code, and message; some errors may also return details. Retain the HTTP status and requestId for troubleshooting.

{
  "requestId": "req-example-001",
  "code": "BadRequest",
  "message": "invalid nextToken"
}

HTTP status	Typical cause	Suggested action
400	Invalid `status`, `nextToken`, or shared-package `orderBy`	Correct parameters; restart the query if the cursor is invalid
401	Missing credentials or authentication failure	Check that the Organization API Key is valid
403	Accessing another organization, using a non-organization identity, or service account capability is not enabled	Check organization ID, credential type, and capabilities; missing capabilities may return `OrganizationPlanCapabilityForbidden`
500	Internal service error	Keep `requestId` and retry later; contact support if failures persist
503	Service temporarily unavailable	Retry with backoff

No packages or an empty filter result is normal and returns HTTP 200 with an empty array.

Seat-month balance batches

GET /v1/organizations/{org_id}/seat-month-batches

Only available for organizations purchased through third-party channels.

Request example:

curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/seat-month-batches" \
  -H "Authorization: Bearer <api_key>"

Response example:

{
  "batches": [
    {
      "batchId": "batch_001",
      "totalSeatMonths": 120,
      "remainingSeatMonths": 80,
      "effectiveAt": "2025-01-01T00:00:00Z",
      "expiresAt": "2025-12-31T23:59:59Z"
    }
  ]
}

Seat-month consumption by period

GET /v1/organizations/{org_id}/seat-month-usages

Only available for organizations purchased through third-party channels.

Query parameters:

Parameter	Type	Description
`periodStart`	string	Required; period range start time in RFC 3339 format
`periodEnd`	string	Required; period range end time in RFC 3339 format; must be later than `periodStart`
`memberId`	string	Optional; filter by organization member ID
`userId`	string	Optional; filter by user ID
`pageSize`	integer	Optional; page size, default 100 and max 500
`pageToken`	string	Optional; pass the `nextToken` from the previous response

Request example:

curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/seat-month-usages?periodStart=2025-01-01T00:00:00Z&periodEnd=2025-04-01T00:00:00Z&pageSize=100" \
  -H "Authorization: Bearer <api_key>"

Response example:

{
  "seatMonthUsages": [
    {
      "memberId": "member_001",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "periodStart": "2025-01-01T00:00:00Z",
      "periodEnd": "2025-02-01T00:00:00Z",
      "consumedSeatMonths": 20.0,
      "refundedSeatMonths": 5.0,
      "netSeatMonths": 15.0
    }
  ],
  "pageSize": 100,
  "nextToken": "2"
}

​Key features

​List member usage events

​Get usage summary

​List organization usage events

​List organization resource packages

​Access requirements

​Query organization shared packages

​Query service account packages

​Status and usage semantics

​Pagination

​Error handling

​Seat-month balance batches

​Seat-month consumption by period

Key features

List member usage events

Get usage summary

List organization usage events

List organization resource packages

Access requirements

Query organization shared packages

Query service account packages

Status and usage semantics

Pagination

Error handling

Seat-month balance batches

Seat-month consumption by period