Usage APIs - Qoder

About this document

Query Credits usage events and summaries by member or organization, and query Shared Add-on Credits, 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.

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	Start time; supports RFC 3339 format or Unix millisecond timestamp
`endDate`	string	No	End time; supports RFC 3339 format or Unix millisecond timestamp
`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": [
    {
      "timestamp": 1719849600000,
      "userId": "user_abc123",
      "userEmail": "user@example.com",
      "source": "IDE",
      "operation": "Agent",
      "modelTier": "Ultimate",
      "credits": 0.35,
      "cost": 0.35
    },
    {
      "timestamp": 1719849500000,
      "userId": "user_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 empty or absent, it indicates the last page.

Response fields

Field	Type	Description
`usages`	array	List of usage records
`usages[].timestamp`	int64	Start time (Unix millisecond timestamp)
`usages[].userId`	string	User ID
`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 (two decimal places); usually equals `credits` or has a fixed conversion ratio
`maxResults`	int32	Page size for this request
`nextToken`	string	Next-page cursor; empty means last page

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	Start time; supports RFC 3339 format or Unix millisecond timestamp
`endDate`	string	No	End time; supports RFC 3339 format or Unix millisecond timestamp
`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": [
    {
      "timestamp": 1719849600000,
      "userId": "user_abc123",
      "userEmail": "user@example.com",
      "source": "IDE",
      "operation": "Agent",
      "modelTier": "Ultimate",
      "credits": 0.35,
      "cost": 0.35
    },
    {
      "timestamp": 1719849500000,
      "userId": "user_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

GET /v1/organizations/{organization_id}/resource-packages Returns all Shared Add-on Credits details for an organization with pagination. The response contains only per-batch information and does not include summaries (aggregate limitValue / usedValue / remainingValue on the client side if needed).

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`, `suspended`. Returns all non-deleted packages when omitted
`orderBy`	string	No	Sort field. Values: `expiresAt` (default), `activatedAt`, `remainingValue`
`order`	string	No	Sort direction. Values: `asc` (default), `desc`
`maxResults`	integer	No	Page size (default 20, max 100)
`nextToken`	string	No	Pagination cursor from the previous response’s `nextToken` field

Success response (200 OK)

With Shared Add-on Credits records and more pages:

{
  "resourcePackages": [
    {
      "id": "pkg-001",
      "name": "Enterprise Annual Pack",
      "source": "purchased",
      "status": "active",
      "activatedAt": "2025-01-01T00:00:00Z",
      "expiresAt": "2026-01-01T00:00:00Z",
      "limitValue": 3000.0,
      "usedValue": 800.0,
      "remainingValue": 2200.0,
      "unit": "credits"
    },
    {
      "id": "pkg-002",
      "name": "Trial Pack",
      "source": "trial",
      "status": "exhausted",
      "activatedAt": "2025-03-15T00:00:00Z",
      "expiresAt": "2025-09-15T00:00:00Z",
      "limitValue": 500.0,
      "usedValue": 500.0,
      "remainingValue": 0.0,
      "unit": "credits"
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjogMn0="
}

Some packages may not return activatedAt (e.g., batches not yet activated); treat it as an optional field during integration.

No Shared Add-on Credits / last page:

{

  "resourcePackages": [],

  "maxResults": 20
}

When nextToken is empty or absent, it indicates the last page.

Response fields

Field	Type	Description
`resourcePackages`	array	List of Shared Add-on Credits
`resourcePackages[].id`	string	Unique credits package ID
`resourcePackages[].name`	string	Credits package name
`resourcePackages[].source`	string	Credits source: `purchased`, `bonus` (gifted), `trial`, `carryOver` (carried over), `refund`, `dev` (development/testing), `sales` (sales-configured)
`resourcePackages[].status`	string	Credits status: `active` (in effect), `exhausted` (quota used up), `expired`, `suspended`
`resourcePackages[].activatedAt`	string	Activation time (RFC 3339 / ISO 8601, UTC; may be empty)
`resourcePackages[].expiresAt`	string	Expiration time (RFC 3339 / ISO 8601, UTC)
`resourcePackages[].limitValue`	float64	Initial total quota
`resourcePackages[].usedValue`	float64	Consumed quota
`resourcePackages[].remainingValue`	float64	Remaining quota (= `limitValue - usedValue`)
`resourcePackages[].unit`	string	Quota unit, typically `credits`
`maxResults`	int32	Page size for this request
`nextToken`	string	Next-page cursor; absent when on the last page

Error responses

Invalid status parameter (400)

{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "invalid status, must be one of: active, exhausted, expired, suspended"
}

Invalid orderBy parameter (400)

{
  "requestId": "req_def456",
  "code": "BadRequest",
  "message": "invalid orderBy field, must be one of: expiresAt, activatedAt, remainingValue"
}

Organization not found or no access (404)

{
  "requestId": "req_jkl012",
  "code": "NotFound",
  "message": "organization not found or not accessible"
}

Status reference

Shared Add-on Credits status machine:

Status	Description	Entry condition
`active`	In effect, consumable	Default status after activation
`exhausted`	Used up	Remaining quota reaches zero (an exhausted package does not automatically transition to `expired` when it expires; it stays `exhausted`)
`expired`	Expired	An hourly scheduled task transitions due `active` packages to `expired`
`suspended`	Suspended	Manually suspended by admin; not consumable

Because expired is set by an hourly async job, there may be up to a 1-hour window between the actual expiration time and the status change. During this window, status is still active but expiresAt < now. For precise “truly available” checks, combine status and expiresAt on the client side:

truly available = status == "active" AND expiresAt > now

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-30T23: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?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

​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

​Path parameters

​Query parameters

​Success response (200 OK)

​Response fields

​Error responses

​Status reference

​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

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

Path parameters

Query parameters

Success response (200 OK)

Response fields

Error responses

Status reference

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