Usage APIs - Qoder

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 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.

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:

{
  "summary": {}
}

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.

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.

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.

Calculation formula

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.

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.

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.

​About this document

​Requirements

​Overview

​Key features

​API list

​1. List usage events

​Path parameters

​Query parameters

​Success response (200 OK)

​Response fields

​2. Get usage summary

​Path parameters

​Query parameters

​Success response (200 OK)

​Response fields

​Error responses

​3. List organization usage events

​Path parameters

​Query parameters

​Success response (200 OK)

​Response fields

​4. List organization Shared Add-on Credits packages

​Access requirements

​Query organization shared packages

​Query service account packages

​Status and usage semantics

​Pagination

​Error handling

​5. List organization seat·month balance batches

​Path parameters

​Query parameters

​Success response (200 OK)

​Response fields

​How to calculate current available seat·month balance

​Error responses

​Status reference

​6. Query periodic seat·month consumption

​Calculation formula

​Path parameters

​Query parameters

​Success response (200 OK)

​Response fields

​Error responses

​Caliber notes

​Usage examples

​List member usage events

​Filter by date range

​List organization usage events

​Filter by source and operation

​Summarize usage by source

​Summarize usage by operation

​List organization Shared Add-on Credits

​Paginate Shared Add-on Credits

​List organization seat·month balance batches

​List only active seat·month balance batches

​Paginate seat·month batches

​Query periodic seat·month consumption

​Query seat·month consumption by member

​Paginate seat·month consumption

​Error codes

About this document

Requirements

Overview

Key features

API list

1. List usage events

Path parameters

Query parameters

Success response (200 OK)

Response fields

2. Get usage summary

Path parameters

Query parameters

Success response (200 OK)

Response fields

Error responses

3. List organization usage events

Path parameters

Query parameters

Success response (200 OK)

Response fields

4. List organization Shared Add-on Credits packages

Access requirements

Query organization shared packages

Query service account packages

Status and usage semantics

Pagination

Error handling

5. List organization seat·month balance batches

Path parameters

Query parameters

Success response (200 OK)

Response fields

How to calculate current available seat·month balance

Error responses

Status reference

6. Query periodic seat·month consumption

Calculation formula

Path parameters

Query parameters

Success response (200 OK)

Response fields

Error responses

Caliber notes

Usage examples

List member usage events

Filter by date range

List organization usage events

Filter by source and operation

Summarize usage by source

Summarize usage by operation

List organization Shared Add-on Credits

Paginate Shared Add-on Credits

List organization seat·month balance batches

List only active seat·month balance batches

Paginate seat·month batches

Query periodic seat·month consumption

Query seat·month consumption by member

Paginate seat·month consumption

Error codes