Cognee Sessions API
Endpoints for listing sessions and reporting usage, cost, and token statistics.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/cognee:cognee-sessions-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Cognee Sessions API
description: Cognee API with Bearer token and Cookie auth
version: 1.0.0
servers:
- url: https://{tenant}.aws.cognee.ai
description: 'Cognee Cloud: your tenant pod, named in the platform.cognee.ai dashboard'
variables:
tenant:
default: your-tenant
description: Your tenant name, shown in the Cognee Cloud dashboard
- url: http://localhost:8000
description: 'Self-hosted: a locally running cognee server'
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: Sessions
description: Endpoints for listing sessions and reporting usage, cost, and token statistics.
paths:
/api/v1/sessions:
get:
tags:
- Sessions
summary: List Sessions
description: 'Paginated list of sessions.
## Request Parameters
- **range** (Literal): Time window on last_activity_at: 24h, 7d, 30d, or all
(default: 30d).
- **status** (Optional[str]): Effective-status filter: running, completed, failed,
or abandoned.
- **limit** (int): Page size, 1-500 (default: 50).
- **offset** (int): Rows to skip for pagination (default: 0).
- **order_by** (str): Sort column: last_activity_at, started_at, ended_at, cost_usd,
tokens_in, or tokens_out (default: last_activity_at).
- **descending** (bool): Sort newest/largest first (default: true).
Response envelope:
```
{
"sessions": [...],
"total": , # rows matching filters before pagination
"limit": ,
"offset": ,
"has_more": ,
}
```'
operationId: list_sessions_api_v1_sessions_get
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- name: range
in: query
required: false
schema:
enum:
- 24h
- 7d
- 30d
- all
type: string
description: 'Time window filtered on last_activity_at: last 24 hours (24h), 7 days (7d), 30 days (30d), or all time (all).'
examples:
- 30d
default: 30d
title: Range
description: 'Time window filtered on last_activity_at: last 24 hours (24h), 7 days (7d), 30 days (30d), or all time (all).'
- name: status
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'Filter by effective status: ''running'', ''completed'', ''failed'', or ''abandoned''. ''abandoned'' is computed at read time: stored status ''running'' with last_activity_at older than SESSION_ABANDON_AFTER_SECONDS (default 30 min). Any other value matches nothing and returns an empty list.'
examples:
- completed
title: Status
description: 'Filter by effective status: ''running'', ''completed'', ''failed'', or ''abandoned''. ''abandoned'' is computed at read time: stored status ''running'' with last_activity_at older than SESSION_ABANDON_AFTER_SECONDS (default 30 min). Any other value matches nothing and returns an empty list.'
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
minimum: 1
description: Page size (max 500).
default: 50
title: Limit
description: Page size (max 500).
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
description: Rows to skip for pagination.
default: 0
title: Offset
description: Rows to skip for pagination.
- name: order_by
in: query
required: false
schema:
type: string
description: 'Column to sort by: last_activity_at, started_at, ended_at, cost_usd, tokens_in, or tokens_out. Unknown values silently fall back to last_activity_at.'
examples:
- cost_usd
default: last_activity_at
title: Order By
description: 'Column to sort by: last_activity_at, started_at, ended_at, cost_usd, tokens_in, or tokens_out. Unknown values silently fall back to last_activity_at.'
- name: descending
in: query
required: false
schema:
type: boolean
description: Sort descending (newest/largest first).
default: true
title: Descending
description: Sort descending (newest/largest first).
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/sessions/stats:
get:
tags:
- Sessions
summary: Get Stats
description: 'Aggregate counters for the dashboard stat cards + status bar.
## Request Parameters
- **range** (Literal): Time window on last_activity_at: 24h, 7d, 30d, or all
(default: 30d).
## Response
Returns a JSON object with:
- **sessions** (int): Number of sessions in the window.
- **total_spend_usd** / **avg_spend_per_session_usd** (float): Cost totals.
- **tokens_in** / **tokens_out** / **tokens_total** (int): Token totals.
- **agent_time_s** / **avg_session_s** (float): Summed and average session duration
in seconds.
- **success_rate** (float): completed / (completed + failed + abandoned); 1.0 when
no session has ended yet.
- **completed** / **failed** / **abandoned** / **running** (int): Effective-status
counts.'
operationId: get_stats_api_v1_sessions_stats_get
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- name: range
in: query
required: false
schema:
enum:
- 24h
- 7d
- 30d
- all
type: string
description: 'Time window filtered on last_activity_at: 24h, 7d, 30d, or all.'
examples:
- 30d
default: 30d
title: Range
description: 'Time window filtered on last_activity_at: 24h, 7d, 30d, or all.'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/sessions/cost-by-model:
get:
tags:
- Sessions
summary: Cost By Model
description: 'Cost + token totals grouped by the model that produced them.
Aggregates ``session_model_usage`` rows (one per session × model),
so a session that used multiple models splits its cost correctly.
Filters on ``session_records.last_activity_at`` to scope by
range — requires a join back to the session row.
## Request Parameters
- **range** (Literal): Time window: 24h, 7d, 30d, or all (default: 30d).'
operationId: cost_by_model_api_v1_sessions_cost_by_model_get
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- name: range
in: query
required: false
schema:
enum:
- 24h
- 7d
- 30d
- all
type: string
description: 'Time window filtered on session_records.last_activity_at: 24h, 7d, 30d, or all.'
examples:
- 30d
default: 30d
title: Range
description: 'Time window filtered on session_records.last_activity_at: 24h, 7d, 30d, or all.'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/sessions/with-agent-info:
get:
tags:
- Sessions
summary: List Sessions With Agent Info
description: 'Session records merged with their agent-connection metadata (CLO-434).
Joins ``session_records`` to the agent-connections registry on
``session_id`` so the cloud UI can group/filter usage by client
(Claude Code, Codex, Slack, MCP, ...) without a second round
trip. When no registered connection matches a session, the
agent type is inferred from the session_id/origin_function
prefix convention (e.g. ``claude-code-...``, ``codex-...``).
Memory sources are intentionally omitted — per-agent dataset
attribution isn''t reliably populated yet.
Response envelope mirrors ``GET /api/v1/sessions``, with each
session additionally carrying ``agent_type``, ``agent_source``,
``agent_session_name``, and ``origin_function``.
## Query Parameters
- **descending** (bool): Sort in descending order. Defaults to True.
- **limit** (int): Page size (max 500). Defaults to 50.
- **offset** (int): Rows to skip for pagination. Defaults to 0.
- **order_by** (str): Column to sort by. Defaults to ''last_activity_at''.
- **range** (Literal[''24h'', ''7d'', ''30d'', ''all'']): Time window filtered on last_activity_at:
24h, 7d, 30d, or all. Defaults to ''30d''.
- **status** (Optional[str]): Effective-status filter: running, completed, failed, or
abandoned.'
operationId: list_sessions_with_agent_info_api_v1_sessions_with_agent_info_get
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- name: range
in: query
required: false
schema:
enum:
- 24h
- 7d
- 30d
- all
type: string
description: 'Time window filtered on last_activity_at: 24h, 7d, 30d, or all.'
examples:
- 30d
default: 30d
title: Range
description: 'Time window filtered on last_activity_at: 24h, 7d, 30d, or all.'
- name: status
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'Effective-status filter: running, completed, failed, or abandoned.'
title: Status
description: 'Effective-status filter: running, completed, failed, or abandoned.'
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
minimum: 1
description: Page size (max 500).
default: 50
title: Limit
description: Page size (max 500).
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
description: Rows to skip for pagination.
default: 0
title: Offset
description: Rows to skip for pagination.
- name: order_by
in: query
required: false
schema:
type: string
default: last_activity_at
title: Order By
- name: descending
in: query
required: false
schema:
type: boolean
default: true
title: Descending
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/sessions/cost-by-user-agent:
get:
tags:
- Sessions
summary: Cost By User Agent
description: 'Cost + token totals grouped by (user, agent type) — feeds a
"who spends the most, with which agent" chart (CLO-434 follow-up).
Visibility matches every other endpoint in this router: the
caller, their child agents, and dataset-shared sessions. On top
of that base scope, a tenant owner/admin (same check
``GET /tenants/{id}/users`` uses) additionally sees every
member''s spend. A regular member — or anyone with no tenant,
i.e. single-user/local mode — just keeps the base scope rather
than being denied outright.
## Query Parameters
- **range** (Literal[''24h'', ''7d'', ''30d'', ''all'']): Time window filtered on last_activity_at:
24h, 7d, 30d, or all. Defaults to ''30d''.'
operationId: cost_by_user_agent_api_v1_sessions_cost_by_user_agent_get
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- name: range
in: query
required: false
schema:
enum:
- 24h
- 7d
- 30d
- all
type: string
description: 'Time window filtered on last_activity_at: 24h, 7d, 30d, or all.'
examples:
- 30d
default: 30d
title: Range
description: 'Time window filtered on last_activity_at: 24h, 7d, 30d, or all.'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/sessions/{session_id}:
get:
tags:
- Sessions
summary: Get Session Detail
description: 'Get session detail — GET /api/v1/sessions/\{session_id\}.
## Path Parameters
- **session_id** (str): Client-supplied session identifier; the same value passed as
session_id to POST /api/v1/remember.'
operationId: get_session_detail_api_v1_sessions__session_id__get
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- name: session_id
in: path
required: true
schema:
type: string
description: Client-supplied session identifier; the same value passed as session_id to POST /api/v1/remember.
examples:
- claude-code-1718000000
title: Session Id
description: Client-supplied session identifier; the same value passed as session_id to POST /api/v1/remember.
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-Api-Key
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
CookieAuth:
type: apiKey
in: cookie
name: auth_token
x-provenance:
method: harvested
publisher: Cognee
source: https://docs.cognee.ai/cognee_openapi_spec.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)