Organizations, Usage & License

These endpoints provide access to organizational resources, usage metrics, and license information.

List Organizations

GET /v1/organizations

Returns the organizations accessible to the authenticated identity.

• API key: Returns the single organization the key belongs to.
• JWT: Returns all organizations the user is a member of.

Scope required (API key): org:read

Response

{
  "data": [
    {
      "id": "org-uuid",
      "name": "Ananke Research",
      "slug": "ananke-research",
      "avatarUrl": "https://...",
      "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	Caller’s role: "owner", "member", 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": "org-uuid",
  "name": "Ananke Research",
  "slug": "ananke-research",
  "avatarUrl": "https://...",
  "memberCount": 5,
  "createdAt": "2025-01-10T08:00:00.000Z"
}

Errors

Status	Code	When
403	FORBIDDEN	Caller is not a member of this organization
404	NOT_FOUND	Organization does not exist

Usage Summary

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

Returns usage metrics for the current billing period.

Scope required (API key): usage:read

Path Parameters

Parameter	Type	Description
orgId	uuid	Organization ID

Response

{
  "simulationRuns": 142,
  "apiCalls": 1830,
  "tickCount": 284000,
  "limits": {
    "maxSimulationRuns": 1000,
    "maxTicksPerRun": 10000
  },
  "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	Total API calls this period
tickCount	number	Total ticks computed this period
limits	object	Current plan 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 across recent billing periods.

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 to return (1–12)

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 current license and subscription details for an organization.

Scope required (API key): org:read

Path Parameters

Parameter	Type	Description
orgId	uuid	Organization ID

Response

{
  "id": "lic-uuid",
  "tier": "professional",
  "status": "active",
  "limits": {
    "maxSimulationRuns": 1000,
    "maxTicksPerRun": 10000,
    "maxConcurrentSSE": 5
  },
  "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", "professional", "enterprise", or "strategic"
status	string	License status
limits	object	Tier-specific limits
currentPeriodStart	string | null	Current billing period start
currentPeriodEnd	string | null	Current billing period end
hasStripeSubscription	boolean	Whether a Stripe subscription is attached

Errors

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