Usage APIs - Qoder

About this document

Query Credits usage events and summaries by member or organization, and query Shared Add-on Credits details for an organization. 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)
`nextCredits`	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,
  "nextCredits": "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 nextCredits 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
`nextCredits`	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

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

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)
`Unauthorized`	401	API key missing or invalid
`Forbidden`	403	No permission to access this organization
`NotFound`	404	Member not found
`InternalError`	500	Internal server error

Error response shape: see Error responses in Conventions.

Documentation Index

​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

​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

​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

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

Error codes