Organizations, Usage & License

These endpoints provide access to organization details, usage metrics, and license information. Authentication is required. API key scopes apply as listed. Scope checks do not apply to JWT callers. API keys access their own organization. JWT callers need membership in the requested organization.

All five endpoints can return 401, 403, 429, or 500. See HTTP Status Codes for shared errors. The examples show illustrative stored values, rather than license tier defaults. Some limits entries are explicitly omitted.

List Organizations

GET /v1/organizations

Returns the organizations accessible to the authenticated identity. The list is not paginated.

• API key: Returns the single organization the key belongs to, or an empty list if that organization is absent.
• JWT: Returns all organizations that the user belongs to.

Scope required (API key): org:read

Response

{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Ananke Research",
      "slug": "ananke-research",
      "avatarUrl": null,
      "role": "owner",
      "createdAt": "2025-01-10T08:00:00.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
id	uuid	Organization ID
name	string	Display name
slug	string	URL-friendly identifier
avatarUrl	string | null	Avatar image URL
role	string	JWT membership role (owner, admin, member, viewer) or api_key
createdAt	string	ISO 8601 timestamp

Get Organization

GET /v1/organizations/{id}

Returns details for a single organization, including member count.

Scope required (API key): org:read

Path Parameters

Parameter	Type	Description
id	uuid	Organization ID

Response

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Ananke Research",
  "slug": "ananke-research",
  "avatarUrl": null,
  "memberCount": 5,
  "createdAt": "2025-01-10T08:00:00.000Z"
}

Errors

Status	Code	When
403	FORBIDDEN	Missing scope, mismatched API key organization, or missing JWT membership
404	NOT_FOUND	Organization does not exist

Usage Summary

GET /v1/organizations/{orgId}/usage/summary

Returns recorded usage for the current calendar-month billing period. The server computes calendar boundaries in its timezone and returns them as UTC timestamps. A missing organization license returns 404 NOT_FOUND when the endpoint loads the limits.

Scope required (API key): usage:read

Path Parameters

Parameter	Type	Description
orgId	uuid	Organization ID

Response

{
  "simulationRuns": 142,
  "apiCalls": 1830,
  "tickCount": 284000,
  "limits": {
    "maxSimulationsPerMonth": 1000,
    "maxTicksPerSimulation": 10000
    // Other stored limits omitted
  },
  "periodStart": "2025-06-01T00:00:00.000Z",
  "periodEnd": "2025-07-01T00:00:00.000Z"
}

Response Fields

Field	Type	Description
simulationRuns	number	Simulations created this period
apiCalls	number	Recorded API-key-authenticated requests this period
tickCount	number	Total ticks computed this period
limits	object	Stored organization license limits
periodStart	string	Billing period start (ISO 8601)
periodEnd	string	Billing period end (ISO 8601)

Usage History

GET /v1/organizations/{orgId}/usage/history

Returns usage metrics for the current billing period first, followed by preceding calendar months. Period boundaries use the server’s timezone and are returned as UTC timestamps.

Scope required (API key): usage:read

Path Parameters

Parameter	Type	Description
orgId	uuid	Organization ID

Query Parameters

Parameter	Type	Default	Description
periods	integer	6	Number of billing periods, clamped to 1 to 12

The handler uses integer parsing. Zero or an unparseable value uses 6. The example shows a two-period response, including the current period.

Response

{
  "data": [
    {
      "periodStart": "2025-06-01T00:00:00.000Z",
      "periodEnd": "2025-07-01T00:00:00.000Z",
      "simulationRuns": 142,
      "apiCalls": 1830,
      "tickCount": 284000
    },
    {
      "periodStart": "2025-05-01T00:00:00.000Z",
      "periodEnd": "2025-06-01T00:00:00.000Z",
      "simulationRuns": 98,
      "apiCalls": 1204,
      "tickCount": 196000
    }
  ]
}

License Information

GET /v1/organizations/{orgId}/license

Returns the organization’s stored license and subscription details. The lookup does not filter by license status.

Scope required (API key): org:read

Path Parameters

Parameter	Type	Description
orgId	uuid	Organization ID

Response

{
  "id": "22222222-2222-4222-8222-222222222222",
  "tier": "professional",
  "status": "active",
  "limits": {
    "maxSimulationsPerMonth": 1000,
    "maxTicksPerSimulation": 10000
    // Other stored limits omitted
  },
  "currentPeriodStart": "2025-06-01T00:00:00.000Z",
  "currentPeriodEnd": "2025-07-01T00:00:00.000Z",
  "hasStripeSubscription": true
}

Response Fields

Field	Type	Description
id	uuid	License ID
tier	string	community, research, evaluation, professional, enterprise, strategic, or licensing
status	string	trialing, active, past_due, canceled, or unpaid
limits	object	Tier-specific limits
currentPeriodStart	string | null	Current billing period start
currentPeriodEnd	string | null	Current billing period end
hasStripeSubscription	boolean	Whether the license has a Stripe subscription ID

Errors

Status	Code	When
403	FORBIDDEN	Caller does not have access to this organization
404	NOT_FOUND	No license found for this organization.