CortexDB Docs
Docs for CortexDB 0.12.8, the version running on CortexDB Cloud (api.cortexdb.ai).
API Reference

/v1/plan and /v1/usage

An account's plan, limits and usage on CortexDB Cloud (GET /v1/plan, operator plan routes), and per-scope storage and activity on any server (GET /v1/usage).

GET
/v1/plan

Authorization

bearer
AuthorizationBearer <token>

PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller. On a cluster data node a PASETO/JWT bearer (not the static key) gets 503 REVOCATION_UNAVAILABLE (retriable) on any route while the node's revocation lease has expired: the metadata group has not confirmed its revocation set for 10 s, or the node has just started. A single-node server never returns it.

In: header

Query Parameters

scope?string

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/plan"
{  "subtree": "string",  "plan": "free",  "overrides": {},  "updated_at": 0,  "limits": {    "max_memories": 0,    "max_recalls_month": 0,    "max_answers_month": 0,    "max_tenants": 0,    "read_per_second": 0,    "read_burst": 0,    "write_per_second": 0,    "write_burst": 0  },  "usage": {    "memories": 0,    "recalls_this_month": 0,    "answers_this_month": 0,    "tenants": 0  },  "memory_unit_chars": 0,  "month": "string",  "resets_at": "2019-08-24T14:15:22Z",  "upgrade_url": "string"}
GET
/v1/usage

Authorization

bearer
AuthorizationBearer <token>

PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller. On a cluster data node a PASETO/JWT bearer (not the static key) gets 503 REVOCATION_UNAVAILABLE (retriable) on any route while the node's revocation lease has expired: the metadata group has not confirmed its revocation set for 10 s, or the node has just started. A single-node server never returns it.

In: header

Query Parameters

scope*string

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/usage?scope=string"
{  "scope": "string",  "events_stored": 0,  "events_capped": true,  "episodes": 0,  "facts": 0,  "entities": 0,  "recalls_lifetime": 0,  "recalls_this_month": 0,  "source": "string",  "storage": {    "events": 0,    "bytes": 0,    "capped": true  },  "activity": {    "subtree": "string",    "tenants": 0,    "capped": true,    "reads": 0,    "writes": 0,    "write_bytes": 0,    "erasures": 0,    "first_at": 0,    "last_at": 0,    "month": "string",    "reads_month": 0,    "answers_month": 0,    "errors_5xx": 0,    "errors_4xx": 0,    "refused_plan": 0,    "refused_rate": 0,    "errors_5xx_month": 0,    "errors_4xx_month": 0,    "refused_plan_month": 0,    "refused_rate_month": 0,    "last_error_at": 0,    "last_error_code": "string",    "storage_events": 0,    "storage_bytes": 0,    "storage_capped": true  }}
GET
/v1/admin/plans/{subtree}

Authorization

bearer
AuthorizationBearer <token>

PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller. On a cluster data node a PASETO/JWT bearer (not the static key) gets 503 REVOCATION_UNAVAILABLE (retriable) on any route while the node's revocation lease has expired: the metadata group has not confirmed its revocation set for 10 s, or the node has just started. A single-node server never returns it.

In: header

Path Parameters

subtree*string

A tenant subtree exactly (org:acct_42)

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/admin/plans/string"
{  "subtree": "string",  "plan": "free",  "overrides": {},  "updated_at": 0,  "limits": {    "max_memories": 0,    "max_recalls_month": 0,    "max_answers_month": 0,    "max_tenants": 0,    "read_per_second": 0,    "read_burst": 0,    "write_per_second": 0,    "write_burst": 0  },  "usage": {    "memories": 0,    "recalls_this_month": 0,    "answers_this_month": 0,    "tenants": 0  },  "memory_unit_chars": 0,  "month": "string",  "resets_at": "2019-08-24T14:15:22Z",  "upgrade_url": "string"}
PUT
/v1/admin/plans/{subtree}

Authorization

bearer
AuthorizationBearer <token>

PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller. On a cluster data node a PASETO/JWT bearer (not the static key) gets 503 REVOCATION_UNAVAILABLE (retriable) on any route while the node's revocation lease has expired: the metadata group has not confirmed its revocation set for 10 s, or the node has just started. A single-node server never returns it.

In: header

Path Parameters

subtree*string

A tenant subtree exactly (org:acct_42)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/v1/admin/plans/string" \  -H "Content-Type: application/json" \  -d '{    "plan": "free"  }'
{  "subtree": "string",  "plan": "free",  "overrides": {},  "updated_at": 0,  "limits": {    "max_memories": 0,    "max_recalls_month": 0,    "max_answers_month": 0,    "max_tenants": 0,    "read_per_second": 0,    "read_burst": 0,    "write_per_second": 0,    "write_burst": 0  },  "usage": {    "memories": 0,    "recalls_this_month": 0,    "answers_this_month": 0,    "tenants": 0  },  "memory_unit_chars": 0,  "month": "string",  "resets_at": "2019-08-24T14:15:22Z",  "upgrade_url": "string"}
GET
/v1/admin/usage/subtrees

Authorization

bearer
AuthorizationBearer <token>

PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller. On a cluster data node a PASETO/JWT bearer (not the static key) gets 503 REVOCATION_UNAVAILABLE (retriable) on any route while the node's revocation lease has expired: the metadata group has not confirmed its revocation set for 10 s, or the node has just started. A single-node server never returns it.

In: header

Query Parameters

prefix?string

Only subtrees starting with it (e.g. org:b7/)

after?string
limit?integer

At most 100 with include_storage

Range1 <= value <= 10000
Default1000
include_storage?string

0.12.8: add storage_events, storage_bytes and storage_capped per subtree. Walks each subtree's rows (up to 1,000,000 each) on the DB lane, so a page holds at most 100 subtrees.

Value in

  • "1"
  • "true"

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/admin/usage/subtrees"
{  "tenant_depth": 0,  "items": [    {      "subtree": "string",      "tenants": 0,      "capped": true,      "reads": 0,      "writes": 0,      "write_bytes": 0,      "erasures": 0,      "first_at": 0,      "last_at": 0,      "month": "string",      "reads_month": 0,      "answers_month": 0,      "errors_5xx": 0,      "errors_4xx": 0,      "refused_plan": 0,      "refused_rate": 0,      "errors_5xx_month": 0,      "errors_4xx_month": 0,      "refused_plan_month": 0,      "refused_rate_month": 0,      "last_error_at": 0,      "last_error_code": "string",      "storage_events": 0,      "storage_bytes": 0,      "storage_capped": true    }  ],  "next_after": null}

GET /v1/plan (hosted plans)

On CortexDB Cloud, or any server with CORTEX_PLANS=1 (v0.12.6+), each account is a tenant subtree (org:acct_42) with a plan. GET /v1/plan answers the caller's own account: without a query, the account its token's first scope grant names; with ?scope=, the account of a scope the caller can read. It answers plan, overrides, limits (null is unlimited: max_memories, max_recalls_month, max_answers_month, max_tenants, and the per-second read and write rates and bursts), usage (memories, recalls_this_month, answers_this_month, tenants), memory_unit_chars (2000), month, resets_at and upgrade_url. What each limit counts and the 402 PLAN_LIMIT_REACHED a request past one gets: Plans and limits. With plans off (a self-hosted server) these routes answer 404 NOT_FOUND.

Setting a plan (operator)

GET /v1/admin/plans/{subtree} and PUT /v1/admin/plans/{subtree} are for a trusted operator only (the cloud's website sets plans with them). PUT takes {"plan": "free" | "starter" | "pro" | "enterprise", "overrides": {...}}, where overrides may set max_memories, max_recalls_month, max_answers_month, max_tenants (a number, or null for unlimited), read_per_second, read_burst, write_per_second and write_burst. An unknown plan or field is 422 INVALID_BODY; a scope that is not a tenant subtree is 400 INVALID_SUBTREE. Both answer the account's report as GET /v1/plan does. A node re-reads a plan at least every 60 seconds.

GET /v1/usage?scope=

Any server (scope read access). Reports what one scope holds and, since v0.12.4, per-tenant activity:

  • storage: events, bytes and capped, the captured rows the source log holds under the scope and their encoded bytes (a row a forget hid but did not erase still counts).
  • activity, for a scope that is a tenant subtree (its first CORTEX_TENANT_DEPTH segments, by default its root) or above one: reads (recall, recall stream, answer, compose), writes (memories; a bulk counts each item), write_bytes, erasures, first_at and last_at (Unix seconds). Above the tenant depth it is the sum over the tenants under the scope (tenants, capped past 100,000).

The counters are per node and survive a restart (a crash loses at most one CORTEX_USAGE_LEDGER_FLUSH_SECONDS interval). GET /v1/admin/usage/subtrees (trusted operator; prefix, after, limit at most 10,000) pages every tenant's counters in subtree order, with next_after naming the next page. Token and model spend is a separate ledger: Token & Cost Ledger.

/v1/policy

Inspect the effective capability set for an actor+scope and the deployment policy.

/v1/admin

Operational endpoints — health, readiness, metrics, version, and maintenance jobs.

On this page

GET /v1/plan (hosted plans)Setting a plan (operator)GET /v1/usage?scope=