Lite / lite values in this reporting API describe historical usage only; they do not indicate a currently selectable model tier.
About this document
Query Credits usage events and summaries by member or organization, and query Shared Add-on Credits, service account Credits packages, seat·month balance batch details and periodic seat·month consumption for an organization (seat·month batches and consumption only apply to organizations purchased via third-party channels). Complete Get API Key first, then read Conventions.
Requirements
- Valid API key tied to the organization.
Overview
The usage APIs provide member-level Credits usage details and summaries, with filters for dates, sources, operations, and model tiers. They also query service account usage by period, 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.
- Service account usage by period: List available periods and retrieve paginated Credits usage and limits for the selected period.
API list
1. List usage events
GET /v1/organizations/{organization_id}/members/{member_id}/usage-events
Paginated retrieval of aggregated Credits usage records for a specified member.
Path parameters
| Parameter | Type | Required | Description |
|---|
organization_id | string | Yes | Organization ID |
member_id | string | Yes | Member ID |
Query parameters
| Parameter | Type | Required | Description |
|---|
startDate | string | No | Earliest event start time (inclusive); supports RFC 3339 format or Unix millisecond timestamp |
endDate | string | No | 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 | No | Filter by source, comma-separated. Values: IDE, CLI, JetBrains Plugin, Web, QoderWork |
operations | string | No | Filter by operation, comma-separated. Values: Inline Chat, Ask, Agent, Repo Wiki, Quest, Plan Mode, Code Review, Optimize Input, Voice Input, Experts, Image |
modelTiers | string | No | Filter by model tier, comma-separated. Values: Auto, Performance, Efficient, Lite, Ultimate, Vision, Qwen-Coder-Qoder-1.0, Kimi-K2.5, GLM-5, MiniMax-M2.5, DeepSeek-V4.0, Qwen3.5-Plus, Standard, Premium, Enterprise |
maxResults | integer | No | Page size (default 20, max 100) |
nextToken | string | No | Pagination cursor |
Success response (200 OK)
With usage records and more pages:
{
"usages": [
{
"eventId": "019c1234-5678-7abc-8def-0123456789ab",
"timestamp": 1719849600000,
"beginAt": "2024-07-01T16:00:00Z",
"finishAt": "2024-07-01T16:01:00.123Z",
"userId": "user_abc123",
"memberId": "member_abc123",
"userEmail": "user@example.com",
"source": "IDE",
"operation": "Agent",
"modelTier": "Ultimate",
"credits": 0.35,
"cost": 0.35
},
{
"eventId": "019c1234-5678-7abc-8def-0123456789ac",
"timestamp": 1719849500000,
"beginAt": "2024-07-01T15:58:20Z",
"finishAt": "2024-07-01T16:00:00.456Z",
"userId": "user_abc123",
"memberId": "member_abc123",
"source": "CLI",
"operation": "Completion",
"credits": 0.02,
"cost": 0.02
}
],
"maxResults": 20,
"nextToken": "eyJwYWdlIjogMn0="
}
Some records may not return userEmail or modelTier; treat them as optional fields during integration.
No usage records / last page:
{
"usages": [],
"maxResults": 20
}
When nextToken is absent, the response is the last page.
Response fields
| Field | Type | Description |
|---|
usages | array | List of usage records |
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. |
usages[].userId | string | User ID |
usages[].memberId | string | Organization member ID; may be omitted when member enrichment is unavailable |
usages[].userEmail | string | User email (may be empty) |
usages[].source | string | Source: IDE, CLI, JetBrains Plugin, Web, QoderWork |
usages[].operation | string | Operation: Inline Chat, Ask, Agent, Repo Wiki, Quest, Plan Mode, Code Review, Optimize Input, Voice Input, Experts, Image |
usages[].modelTier | string | Model tier (may be empty): Auto, Performance, Efficient, Lite, Ultimate, Vision, Qwen-Coder-Qoder-1.0, Kimi-K2.5, GLM-5, MiniMax-M2.5, DeepSeek-V4.0, Qwen3.5-Plus, Standard, Premium, Enterprise |
usages[].credits | float64 | Credits consumed (two decimal places) |
usages[].cost | float64 | Billing-adjusted cost, rounded down to two decimal places: billingCredits × billingFactor |
maxResults | int32 | Page size for this request |
nextToken | string | Next-page cursor; omitted on the last page |
finishAt can advance as newer usage is reported for the same event. eventId and beginAt remain unchanged.
2. Get usage summary
GET /v1/organizations/{organization_id}/members/{member_id}/usage-summary
Summarize a member's Credits consumption over a given time range by the specified dimension. The time range must not exceed 7 days.
Path parameters
| Parameter | Type | Required | Description |
|---|
organization_id | string | Yes | Organization ID |
member_id | string | Yes | Member ID |
Query parameters
| Parameter | Type | Required | Description |
|---|
startDate | string | Yes | Start time; supports RFC 3339 format or Unix millisecond timestamp |
endDate | string | Yes | End time; supports RFC 3339 format or Unix millisecond timestamp |
groupBy | string | Yes | Grouping dimension: source (by source) or operation (by operation) |
Success response (200 OK)
Grouped by source (**groupBy=source**):
{
"summary": {
"IDE": 12.50,
"CLI": 3.25
}
}
Grouped by operation (**groupBy=operation**):
{
"summary": {
"Agent": 8.40,
"Completion": 5.10,
"Inline Chat": 2.25
}
}
No usage data:
Response fields
| Field | Type | Description |
|---|
summary | object | Summary result; key is the group name (source or operation), value is total Credits |
summary.{key} | float64 | Total Credits consumed by that group (two decimal places) |
Error responses
Missing required parameter (400)
{
"requestId": "req_abc123",
"code": "BadRequest",
"message": "startDate is required"
}
Time range exceeded (400)
{
"requestId": "req_abc123",
"code": "BadRequest",
"message": "date range must not exceed 7 days"
}
Invalid groupBy (400)
{
"requestId": "req_abc123",
"code": "BadRequest",
"message": "groupBy is required and must be 'source' or 'operation'"
}
3. List organization usage events
GET /v1/organizations/{organization_id}/usage-events
Paginated retrieval of aggregated token usage records for all members in the specified organization. The response structure is identical to the member usage events endpoint.
Path parameters
| Parameter | Type | Required | Description |
|---|
organization_id | string | Yes | Organization ID |
Query parameters
| Parameter | Type | Required | Description |
|---|
startDate | string | No | Earliest event start time (inclusive); supports RFC 3339 format or Unix millisecond timestamp |
endDate | string | No | 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 | No | Filter by source, comma-separated. Values: IDE, CLI, JetBrains Plugin, Web, QoderWork |
operations | string | No | Filter by operation, comma-separated. Values: Inline Chat, Ask, Agent, Repo Wiki, Quest, Plan Mode, Code Review, Optimize Input, Voice Input, Experts |
modelTiers | string | No | Filter by model tier, comma-separated. Values: Auto, Performance, Efficient, Lite, Ultimate, Vision, Qwen-Coder-Qoder-1.0, Kimi-K2.5, GLM-5, MiniMax-M2.5, DeepSeek-V4.0, Qwen3.5-Plus, Standard, Premium, Enterprise |
maxResults | integer | No | Page size (default 20, max 100) |
nextToken | string | No | Pagination cursor |
Success response (200 OK)
{
"usages": [
{
"eventId": "019c1234-5678-7abc-8def-0123456789ab",
"timestamp": 1719849600000,
"beginAt": "2024-07-01T16:00:00Z",
"finishAt": "2024-07-01T16:01:00.123Z",
"userId": "user_abc123",
"memberId": "member_abc123",
"userEmail": "user@example.com",
"source": "IDE",
"operation": "Agent",
"modelTier": "Ultimate",
"credits": 0.35,
"cost": 0.35
},
{
"eventId": "019c1234-5678-7abc-8def-0123456789ac",
"timestamp": 1719849500000,
"beginAt": "2024-07-01T15:58:20Z",
"finishAt": "2024-07-01T16:00:00.456Z",
"userId": "user_def456",
"memberId": "member_def456",
"source": "CLI",
"operation": "Ask",
"credits": -0.02,
"cost": -0.02
}
],
"maxResults": 20,
"nextToken": "eyJwYWdlIjogMn0="
}
Some records may not return userEmail or modelTier; treat them as optional fields during integration. The endpoint does not filter out negative Credits records by default; refunds and reversals may also appear.
Response fields
Response fields are identical to "1. List usage events".
4. List organization Shared Add-on Credits 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 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.
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.
5. List organization seat·month balance batches
This API only applies to organizations purchased via third-party channels (e.g., marketplace redemption codes).
GET /v1/organizations/{organization_id}/seat-month-batches
Paginated retrieval of seat·month balance batch details for an organization. The response contains only per-batch information and does not return an aggregate total.
Seat·month balance differs from the remainingSeats field in member statistics. remainingSeats only applies to organizations purchased via non-third-party channels and indicates remaining available seats within purchased seats; seat·month balance indicates how many consumable seat·month batches the organization has left. An organization may top up seat·month balance multiple times, and each batch has its own remaining quantity and expiration time.
Path parameters
| Parameter | Type | Required | Description |
|---|
organization_id | string | Yes | Organization ID |
Query parameters
| Parameter | Type | Required | Description |
|---|
status | string | No | Filter by status. Values: active, exhausted, expired, refunded. Omit to return all batches |
pageSize | integer | No | Page size (default 100, max 500) |
pageToken | string | No | Pagination cursor. Pass the nextToken from the previous response |
Success response (200 OK)
With batches and more pages:
{
"seatMonthBatches": [
{
"id": "batch-001",
"redemptionCodeId": "rc-001",
"status": "active",
"sourceChannel": "REDEMPTION_CODE",
"thirdPartyInstanceId": "inst_xxx",
"productCode": "qoder_team_seat_month",
"reportRequired": true,
"totalSeatMonths": 120.0,
"usedSeatMonths": 30.0,
"remainingSeatMonths": 90.0,
"effectiveAt": "2026-06-01T00:00:00Z",
"expiresAt": "2026-09-01T00:00:00Z",
"createdAt": "2026-06-01T00:00:00Z",
"updatedAt": "2026-06-10T00:00:00Z"
},
{
"id": "batch-002",
"redemptionCodeId": "rc-002",
"status": "exhausted",
"sourceChannel": "ANNUAL_RETURN",
"totalSeatMonths": 30.0,
"usedSeatMonths": 30.0,
"remainingSeatMonths": 0.0,
"effectiveAt": "2026-05-01T00:00:00Z",
"expiresAt": "2026-08-01T00:00:00Z",
"createdAt": "2026-05-01T00:00:00Z",
"updatedAt": "2026-05-20T00:00:00Z"
}
],
"pageSize": 100,
"nextToken": "2"
}
Some batches may not return redemptionCodeId, sourceChannel, thirdPartyInstanceId, or productCode; treat them as optional fields during integration.
No batches / last page:
{
"seatMonthBatches": [],
"pageSize": 100
}
When nextToken is absent, it indicates the last page. When paginating, pass the nextToken from the response as pageToken in the next request.
Response fields
| Field | Type | Description |
|---|
seatMonthBatches | array | List of seat·month balance batches |
seatMonthBatches[].id | string | Batch ID |
seatMonthBatches[].redemptionCodeId | string | Associated redemption code record ID (not the plaintext code); may be empty |
seatMonthBatches[].status | string | Batch status: active, exhausted, expired, refunded |
seatMonthBatches[].sourceChannel | string | Source channel (e.g., redemption code, annual return, marketplace); may be empty |
seatMonthBatches[].thirdPartyInstanceId | string | Third-party instance ID; may be empty |
seatMonthBatches[].productCode | string | Third-party product code; may be empty |
seatMonthBatches[].reportRequired | boolean | Whether marketplace usage reporting is required |
seatMonthBatches[].totalSeatMonths | float64 | Original total seat·months for this batch |
seatMonthBatches[].usedSeatMonths | float64 | Consumed seat·months for this batch |
seatMonthBatches[].remainingSeatMonths | float64 | Remaining seat·months for this batch |
seatMonthBatches[].effectiveAt | string | Effective time (RFC 3339 / ISO 8601, UTC) |
seatMonthBatches[].expiresAt | string | Expiration time (RFC 3339 / ISO 8601, UTC) |
seatMonthBatches[].createdAt | string | Creation time (RFC 3339 / ISO 8601, UTC) |
seatMonthBatches[].updatedAt | string | Last update time (RFC 3339 / ISO 8601, UTC) |
pageSize | int32 | Page size for this request |
nextToken | string | Next-page cursor; absent on the last page |
How to calculate current available seat·month balance
The API does not return a total balance directly. Filter batches with the following conditions, then sum remainingSeatMonths:
available batches = status == "active"
AND effectiveAt <= now
AND expiresAt > now
AND remainingSeatMonths > 0
For example, if 3 batches are returned:
| Batch | Status | Remaining seat·months | Effective time | Expiration time | Counted toward available balance |
|---|
| A | active | 90.0 | Already effective | Not expired | Yes |
| B | exhausted | 0.0 | Already effective | Not expired | No |
| C | active | 20.0 | Not yet effective | Not expired | No |
Current available seat·month total balance is 90.0.
Error responses
Invalid status parameter (400)
{
"requestId": "req_abc123",
"code": "BadRequest",
"message": "invalid status, must be one of: active, exhausted, expired, refunded"
}
Invalid pageToken parameter (400)
{
"requestId": "req_def456",
"code": "BadRequest",
"message": "invalid pageToken"
}
Status reference
| Status | Description | Entry condition |
|---|
active | In effect | Default status after batch creation; not yet exhausted, expired, or refunded |
exhausted | Used up | Batch remaining quantity reaches zero |
expired | Expired | Entered after system expiration reclaim |
refunded | Refunded/voided | Entered via refund or voiding process |
Because the expired status is refreshed asynchronously by a background task, there may be a delay between the actual expiration time and the status transition. For precise "currently available" checks, evaluate status, effectiveAt, expiresAt, and remainingSeatMonths together.
6. Query periodic seat·month consumption
This API only applies to organizations purchased via third-party channels (e.g., marketplace redemption codes). It returns the actual net consumption for marketplace reconciliation/reporting, not all internal seat·month transactions.
GET /v1/organizations/{organization_id}/seat-month-usages
Paginated retrieval of member seat·month consumption for a specified period range at the organization level. The response is aggregated by member and billing period; it does not return seat·month batch details.
netSeatMonths = max(consumedSeatMonths - refundedSeatMonths, 0)
| Field | Description |
|---|
consumedSeatMonths | Seat·months originally consumed by the member in that period |
refundedSeatMonths | Seat·months refunded and attributable to the original seat and period |
netSeatMonths | Actual net consumption for the member in that period |
Historical boundary: The API launch time is 2026-06-24T16:00:00Z. Data before this time may lack completeness due to missing period information; please rely on periods after launch for accurate calculations.
Path parameters
| Parameter | Type | Required | Description |
|---|
organization_id | string | Yes | Organization ID |
Query parameters
| Parameter | Type | Required | Description |
|---|
periodStart | string | Yes | Period range start time, RFC 3339 format, e.g. 2026-06-01T00:00:00Z |
periodEnd | string | Yes | Period range end time, RFC 3339 format, must be later than periodStart |
memberId | string | No | Filter by organization member ID |
userId | string | No | Filter by user ID |
pageSize | integer | No | Page size (default 100, max 500) |
pageToken | string | No | Pagination cursor. Pass the nextToken from the previous response |
Results only include complete billing periods where periodStart >= request periodStart and periodEnd <= request periodEnd. Use actual billing period boundaries for queries.
Success response (200 OK)
With consumption records and more pages:
{
"seatMonthUsages": [
{
"memberId": "member_abc123",
"userId": "user_abc123",
"periodStart": "2026-06-01T00:00:00Z",
"periodEnd": "2026-07-01T00:00:00Z",
"consumedSeatMonths": 20.0,
"refundedSeatMonths": 5.0,
"netSeatMonths": 15.0
},
{
"memberId": "member_def456",
"userId": "user_def456",
"periodStart": "2026-06-01T00:00:00Z",
"periodEnd": "2026-07-01T00:00:00Z",
"consumedSeatMonths": 1.0,
"refundedSeatMonths": 1.0,
"netSeatMonths": 0.0
}
],
"pageSize": 100,
"nextToken": "2"
}
After a full refund, netSeatMonths may be 0. For example, if a member was assigned a seat but never used Credits, and was later removed, the seat·months are returned to the organization and net consumption for that period is 0.
No consumption records / last page:
{
"seatMonthUsages": [],
"pageSize": 100
}
When nextToken is absent, it indicates the last page. Pass the nextToken from the response as pageToken in the next request.
Response fields
| Field | Type | Description |
|---|
seatMonthUsages | array | Member seat·month consumption list |
seatMonthUsages[].memberId | string | Organization member ID |
seatMonthUsages[].userId | string | User ID |
seatMonthUsages[].periodStart | string | Billing period start time, RFC 3339 / ISO 8601 format |
seatMonthUsages[].periodEnd | string | Billing period end time, RFC 3339 / ISO 8601 format |
seatMonthUsages[].consumedSeatMonths | float64 | Original seat·months consumed by member in this period |
seatMonthUsages[].refundedSeatMonths | float64 | Seat·months refunded for member in this period |
seatMonthUsages[].netSeatMonths | float64 | Actual net seat·month consumption for member in this period |
pageSize | int32 | Page size for this request |
nextToken | string | Next-page cursor; absent on the last page |
Error responses
Missing periodStart parameter (400)
{
"requestId": "req_abc123",
"code": "BadRequest",
"message": "periodStart is required"
}
Missing periodEnd parameter (400)
{
"requestId": "req_def456",
"code": "BadRequest",
"message": "periodEnd is required"
}
Invalid time format (400)
{
"requestId": "req_ghi789",
"code": "BadRequest",
"message": "invalid periodStart, must be RFC3339"
}
Invalid time range (400)
{
"requestId": "req_jkl012",
"code": "BadRequest",
"message": "periodStart must be before periodEnd"
}
Caliber notes
Marketplace reporting caliber
This API returns net consumption for marketplace reconciliation/reporting, not all internal seat·month transactions. Internal seat·month records that do not require reporting (e.g., test or gifted quotas) will not appear in the response.
Refund deduction caliber
If a member is removed during the current period and has not used any Credits in that period, the system returns the corresponding seat·months to the organization balance. Refunds meeting the following conditions are deducted from the member's consumption for that period:
| Condition | Description |
|---|
| Same organization | Refund record belongs to the same organization |
| Same seat assignment | Refund record can be linked to the original seat assignment ID |
| Same billing period | Refund record carries the original period start and end times |
| Refund type | Refund transaction is REFUND / INCREASE |
Sorting & pagination
Results are sorted by periodStart descending (newer periods first), then memberId ascending, then userId ascending. Use nextToken from the response for pagination; absence of nextToken means no more pages.
7. Query service account usage by period
Query Credits usage and limits for service accounts in a selected usage period, for usage dashboards and historical reporting. Use the target organization’s Organization API Key. The organization must have service accounts enabled. The organization_id path parameter is required.
List available usage periods
GET /v1/organizations/{organization_id}/service-accounts/usage/periods
Returns the organization’s existing service account usage periods, sorted by end time and then start time in descending order, with the latest period first. If no periods are available, returns 200 OK with {"periods":[]}.
curl --get "https://api.qoder.com/v1/organizations/${ORGANIZATION_ID}/service-accounts/usage/periods" \
-H "Authorization: Bearer ${ORGANIZATION_API_KEY}"
{
"periods": [
{
"periodStart": "2026-09-01T00:00:00.123456789Z",
"periodEnd": "2026-10-01T00:00:00.123456789Z"
}
]
}
periodStart and periodEnd are UTC RFC 3339 strings that preserve fractional seconds, up to 9 digits. Pass both boundaries back exactly as returned; do not truncate fractional seconds or calculate calendar months yourself. Each period includes its start time and excludes its end time.
List service accounts for a usage period
GET /v1/organizations/{organization_id}/service-accounts
| Parameter | Type | Required | Description |
|---|
periodStart | string | No | Period start in RFC 3339 format; must be provided together with periodEnd |
periodEnd | string | No | Period end in RFC 3339 format; must be provided together with periodStart |
status | string | No | Current account status: active or archived; omitted means no status filter |
keyword | string | No | Keyword in the account name or description; up to 500 characters |
maxResults | integer | No | Page size, default 20, maximum 100 |
nextToken | string | No | Pagination cursor from the previous response |
If no period is specified, selects the latest available period, matching the service account list in the management console. If no periods are available, returns the account list with current limits and current-period usage, and omits selectedPeriod.
Explicit start and end times must match an existing service account usage period in the organization. These parameters select a period; they do not aggregate usage over arbitrary time ranges.
Request example
curl --get "https://api.qoder.com/v1/organizations/${ORGANIZATION_ID}/service-accounts" \
-H "Authorization: Bearer ${ORGANIZATION_API_KEY}" \
--data-urlencode "periodStart=2026-09-01T00:00:00.123456789Z" \
--data-urlencode "periodEnd=2026-10-01T00:00:00.123456789Z" \
--data-urlencode "status=active" \
--data-urlencode "maxResults=20"
Success response (200 OK)
The example shows the fields relevant to period usage.
{
"serviceAccounts": [
{
"id": "sa_abc123",
"organizationId": "org_xxx",
"name": "CI Automation",
"status": "active",
"limitAmount": -1,
"usedAmount": 125.5
}
],
"maxResults": 20,
"selectedPeriod": {
"periodStart": "2026-09-01T00:00:00.123456789Z",
"periodEnd": "2026-10-01T00:00:00.123456789Z"
}
}
| Field | Type | Description |
|---|
serviceAccounts | array | Service accounts; an empty array when no accounts match |
serviceAccounts[].id | string | Service account ID |
serviceAccounts[].name | string | Current service account name |
serviceAccounts[].status | string | Current account status: active or archived |
serviceAccounts[].usedAmount | number | Credits accumulated in the selected period; 0 when no usage exists |
serviceAccounts[].limitAmount | number | Credits limit for the selected period; -1 means unlimited and 0 means frozen. Missing historical limits are returned as -1 |
selectedPeriod | object | Selected period, containing periodStart and periodEnd; omitted when no periods are available |
maxResults | integer | Page size |
nextToken | string | Cursor for the next page; omitted when there are no more pages |
With a period selected and no status filter, the list includes currently active accounts and archived accounts with positive usage in that period. status=archived also returns only archived accounts with positive usage in the selected period. Names, descriptions, and account statuses are current values, not historical snapshots.
Usage is accumulated asynchronously and may have a short delay. Usage for an individual service account may exceed its configured limit. This API reports period usage and does not replace billing statements.
Keep the period, status, keyword, and maxResults unchanged when paginating with nextToken. If the first request omits the period, explicitly pass both boundaries from selectedPeriod on subsequent pages to keep the same period across a period rollover.
Error handling
Returns 400 Bad Request if only one period boundary is provided, a timestamp is invalid, the end is not after the start, or the period does not exist. Missing authentication returns 401; access to another organization or an organization without service accounts enabled returns 403.
8. List service account usage events
GET /v1/organizations/{organization_id}/usage/service-accounts/{service_account_id}/events
Use the target organization’s API key (Authorization: Bearer <organization_api_key>) for the following two service account usage endpoints. Service account keys and short-lived tokens cannot call these endpoints. Replace example UUIDs with actual resource IDs from the organization.
Path parameters
| Parameter | Type | Required | Description |
|---|
organization_id | string | Yes | Organization ID |
service_account_id | string | Yes | Service account ID |
Query parameters
| Parameter | Type | Required | Description |
|---|
startDate, endDate | string | Yes | Time range above |
sources | string | No | Comma-separated source names; all by default |
operations | string | No | Comma-separated operation names; all by default |
modelTiers | string | No | Comma-separated model tier names; all by default |
sessionId | string | No | Exact session ID; may appear at most once |
maxResults | integer | No | Default 20, valid range 1–100; invalid values return 400 |
nextToken | string | No | Cursor from the preceding response |
Common sources include IDE, CLI, JetBrains Plugin, Web, Qoder, QoderWork, and QoderWake. Common operations include Inline Chat, Ask, Agent, Repo Wiki, Quest Mode, Plan Mode, Code Review, Optimize Input, Voice Input, and Experts. These are examples, not exhaustive enums. Model tier names describe usage records, not a list of currently selectable models.
Both startDate and endDate are required. Accepts RFC 3339 or positive Unix milliseconds, for example 2026-07-01T00:00:00Z or 1782864000000. Both must represent instants after the Unix epoch, startDate must precede endDate, and the range must not exceed 7 days.
Filtering uses event start time and includes both endpoints. Avoid including the same boundary in adjacent windows.
Success response (200 OK)
{
"events": [
{
"eventId": "019c1234-5678-7abc-8def-0123456789ac",
"timestamp": 1782864000000,
"durationMs": 800,
"principalType": "serviceAccount",
"serviceAccountId": "019c1234-5678-7abc-8def-012345678901",
"sessionId": "session_def456",
"source": "CLI",
"operation": "Agent",
"modelTier": "Standard",
"credits": 0.5
}
],
"maxResults": 20,
"nextToken": "eyJwYWdlIjoyfQ=="
}
Response fields
| Field | Type | Description |
|---|
events | array | Current page, newest event start time first |
events[].eventId | string | Stable unique event ID |
events[].timestamp | int64 | Event start in Unix milliseconds |
events[].durationMs | int64 | Duration in milliseconds; 0 if end precedes start |
events[].principalType | string | Always serviceAccount |
events[].serviceAccountId | string | Required service account ID |
events[].sessionId, events[].source, events[].operation | string | Session, source, and operation |
events[].modelTier | string | Optional model tier |
events[].credits | float64 | Credits for this event, zero or greater |
maxResults | int32 | Page size used |
nextToken | string | Optional next-page cursor |
No data returns {"events":[],"maxResults":20}. The final page omits nextToken and can still contain events. Pass the returned cursor unchanged while retaining the original query filters; do not construct it from the example.
Archived service accounts retain queryable history; missing accounts or accounts in another organization return 404.
9. Get service account net usage summary
GET /v1/organizations/{organization_id}/usage/service-accounts/{service_account_id}/summary
Returns net Credits for the specified service account over the requested window. Archived accounts remain queryable; missing accounts or accounts outside the organization return 404.
Path parameters
| Parameter | Type | Required | Description |
|---|
organization_id | string | Yes | Organization ID |
service_account_id | string | Yes | Service account ID |
Query parameters
| Parameter | Type | Required | Description |
|---|
startDate | string | Yes | Start time, RFC 3339 or positive Unix milliseconds |
endDate | string | Yes | End time, RFC 3339 or positive Unix milliseconds |
Only startDate and endDate are accepted. Extra parameters such as sources or groupBy return 400.
Both startDate and endDate are required. Accepts RFC 3339 or positive Unix milliseconds, for example 2026-07-01T00:00:00Z or 1782864000000. Both must represent instants after the Unix epoch, startDate must precede endDate, and the range must not exceed 7 days.
Filtering uses event start time and includes both endpoints. Avoid including the same boundary in adjacent windows.
Success response (200 OK)
The event list includes usage only for visible sources and operations and excludes negative adjustments. The summary includes negative adjustments. Events are rounded down to two decimal places individually, while the summary is rounded down after aggregation. The sum of the listed events can therefore differ from the summary.
Response fields
| Field | Type | Description |
|---|
credits | float64 | Net Credits including negative adjustments; 0 when there is no usage. The total can be negative. |
Error responses
These errors apply to the service account usage event and summary endpoints on this page.
{
"requestId": "req_abc123",
"code": "BadRequest",
"message": "startDate is required"
}
| HTTP | Typical code | Cause |
|---|
400 | BadRequest | Missing or invalid parameters, invalid cursor/page size, unsupported query parameters, or excessive date window |
401 | Unauthorized | Missing or invalid credential |
403 | Forbidden | Credential is not an organization API key or belongs to another organization |
404 | NotFound | Service account missing or outside the organization |
500 | InternalError | Internal failure |
Errors may retain a downstream business code. A common message is date range must not exceed 7 days.
Usage examples
List member usage events
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-events?maxResults=20" \
-H "Authorization: Bearer <api_key>"
Filter by date range
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-events?startDate=2025-06-01T00:00:00Z&endDate=2025-06-07T23:59:59Z" \
-H "Authorization: Bearer <api_key>"
List organization usage events
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/usage-events?maxResults=20" \
-H "Authorization: Bearer <api_key>"
Filter by source and operation
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-events?sources=IDE&operations=Ask,Agent" \
-H "Authorization: Bearer <api_key>"
Summarize usage by source
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-summary?startDate=2026-03-13T00:00:00Z&endDate=2026-03-20T00:00:00Z&groupBy=source" \
-H "Authorization: Bearer <api_key>"
Summarize usage by operation
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-summary?startDate=2026-03-13T00:00:00Z&endDate=2026-03-20T00:00:00Z&groupBy=operation" \
-H "Authorization: Bearer <api_key>"
List organization Shared Add-on Credits
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/resource-packages?status=active&orderBy=expiresAt&order=asc&maxResults=20" \
-H "Authorization: Bearer <api_key>"
Paginate Shared Add-on Credits
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/resource-packages?status=active&orderBy=expiresAt&order=asc&maxResults=20&nextToken=eyJwYWdlIjogMn0%3D" \
-H "Authorization: Bearer <api_key>"
nextToken may contain URL-reserved characters; URL-encode it when passing as a query parameter (e.g., = → %3D).
List organization seat·month balance batches
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-batches?pageSize=100" \
-H "Authorization: Bearer <api_key>"
List only active seat·month balance batches
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-batches?status=active&pageSize=100" \
-H "Authorization: Bearer <api_key>"
Paginate seat·month batches
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-batches?pageToken=2" \
-H "Authorization: Bearer <api_key>"
pageToken is from the nextToken of the previous page response.
Query periodic seat·month consumption
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-usages?periodStart=2026-06-01T00:00:00Z&periodEnd=2026-07-01T00:00:00Z&pageSize=100" \
-H "Authorization: Bearer <api_key>"
Query seat·month consumption by member
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-usages?periodStart=2026-06-01T00:00:00Z&periodEnd=2026-07-01T00:00:00Z&memberId=member_xxx&pageSize=100" \
-H "Authorization: Bearer <api_key>"
Paginate seat·month consumption
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-usages?periodStart=2026-06-01T00:00:00Z&periodEnd=2026-08-01T00:00:00Z&pageSize=20&pageToken=2" \
-H "Authorization: Bearer <api_key>"
pageToken is from the nextToken of the previous page response.
List service account usage events
curl -X GET "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/usage/service-accounts/019c1234-5678-7abc-8def-012345678901/events?startDate=2026-07-01T00:00:00Z&endDate=2026-07-08T00:00:00Z" \
-H "Authorization: Bearer <organization_api_key>"
Get service account net usage summary
curl -X GET "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/usage/service-accounts/019c1234-5678-7abc-8def-012345678901/summary?startDate=2026-07-01T00:00:00Z&endDate=2026-07-08T00:00:00Z" \
-H "Authorization: Bearer <organization_api_key>"
Error codes
| Error code | HTTP status | Description |
|---|
BadRequest | 400 | Invalid request parameters (e.g., empty member_id, incorrect date format, time range exceeded, invalid groupBy, invalid status, invalid pageToken, periodStart/periodEnd missing or invalid) |
Unauthorized | 401 | API key missing or invalid |
Forbidden | 403 | No permission to access this organization |
NotFound | 404 | Resource not found |
InternalError | 500 | Internal server error |
Error response shape: see Error responses in Conventions.