> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praxis-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get tool usage and prompt cache census
> Aggregate-only census of tool usage and prompt-cache behaviour over conversation history. The response carries tool names, model names, lane names, bucket labels and counts. It never carries a user id, a Digital Twin id, a conversation id, a question or an answer. Distinct users and twins are returned as counts. One request runs one bounded view. The window is at most 31 days (a wider window is rejected, never clamped) and defaults to the last 7 days. Results are cached. An administrator of one Digital Twin only ever sees that twin. Only real turns are counted - rows stamped by the turn save path (every saved turn since 2026-09-10) plus avatar embed sessions. Uploads, sign-in events and other non-turn history rows are left out. A window that starts before 2026-09-10 is answered with a warning, because older turns carry no marker. Lanes - qanda is a single-shot text turn, convo is one Convo Mode (realtime) or avatar embed session per row, agentic is a turn that ran a conductor, background workers or a plan execution (its tools are the conductor's own), and workers (tools view only) counts the tools that the background workers of a turn ran. A tool that appears only under workers is never called by a single-shot turn. Labels are vetted - a tool label is a platform tool name, mcp_bridged or other, and a model label that does not look like a model name is returned as other. Tools reached through an MCP connector are counted together as mcp_bridged, because their stored name carries the connector label chosen by the customer. The twins count treats the personal scope (no twin) as one twin. Approximations - sameSlotTurns counts turns that share a clock-aligned five-minute slot with an earlier turn of the same conversation, which is a lower bound on follow-ups that land inside a five-minute prompt cache. A conversation is a user, a twin and a course_id, and a row without course_id counts as its own conversation.
## OpenAPI
````yaml /mdx/api-reference/admin/admin-api.json post /api/admin/histories/charts/tools
openapi: 3.0.0
info:
title: Pria Admin API
version: 2.0.119
description: >-
Pria API Documentation Praxis's developer platform is a core part of our
mission to empower organizations to grow better. Our APIs are designed to
enable teams of any shape or size to build robust integrations that help
them customize and get the most value out of Pria. All Pria APIs are built
using REST conventions and designed to have a predictable URL structure.
They use many standard HTTP features, including methods (POST,
GET, PUT, DELETE) and error response codes.
All API calls are
made under https://hiimpria.ai/api and all responses return standard JSON.
In these docs, you'll find lists of all available endpoints for a given API,
along with interactive code blocks for building requests. For walkthroughs
of basic usage for these APIs, check out the API guides.
servers:
- url: https://pria.praxislxp.com
description: Pria API Server
security: []
tags:
- name: Authentication
description: User authentication, registration, and password management (/api/auth)
- name: OAuth
description: OAuth authentication providers - Google, GitHub, SSO (/api/auth/oauth)
- name: User
description: User profile management and account operations (/api/user)
- name: User Institutions
description: User institution memberships and switching (/api/user/institution)
- name: User Tools
description: Available tools for authenticated users (/api/user/tools)
- name: Institutions
description: Institution settings and configuration (/api/user/institution)
- name: Conversation
description: AI conversation and Q&A endpoints (/api/ai)
- name: Realtime
description: Real-time voice AI and WebRTC sessions (/api/ai/rt)
- name: Assistant
description: AI assistant configuration and management (/api/user/assistant)
- name: History
description: Conversation history and favorites (/api/user/history)
- name: RAG
description: >-
Document upload, embedding, and retrieval-augmented generation
(/api/user/files, /api/user/rag)
- name: Setting
description: Instance variables and settings management (/api/user/setting)
- name: Branding
description: Digital twin branding and customization (/api/agent/branding)
- name: Agent
description: Agent engagement and session management (/api/agent)
- name: SDK Launch
description: >-
SDK launch token signing and verification for secure iframe embedding
(/api/auth/sdk-sign, /api/auth/sdk-verify)
- name: Testing
description: Health checks, diagnostics, and test endpoints (/api/test)
- name: Admin Accounts
description: Account management for super admins (/api/admin/account)
- name: Admin Institutions
description: Institution management for admins (/api/admin/institution)
- name: Admin Users
description: User management for admins (/api/admin/user)
- name: Admin Entitlements
description: >-
User-institution relationships and permissions
(/api/admin/userInstitution)
- name: Admin Sessions
description: Session management for admins (/api/admin/session)
- name: Admin Histories
description: Conversation history management and analytics (/api/admin/history)
- name: Admin Assistants
description: AI assistant management for admins (/api/admin/assistant)
- name: Admin Questions
description: Institution question and prompt management (/api/admin/question)
- name: Admin Tools
description: Tool configuration management (/api/admin/tool)
- name: Admin AI Models
description: AI model configuration (/api/admin/aimodel)
- name: Admin MCP Servers
description: Model Context Protocol server management (/api/admin/mcpserver)
- name: Admin Feedbacks
description: User feedback management (/api/admin/feedback)
- name: Admin Uploads
description: Upload management (/api/admin/upload)
- name: Admin Charts
description: Analytics and visualization chart management (/api/admin/chart)
- name: Admin Memory
description: Admin inspection and editing of user/instance memory parameters.
- name: Admin Usage Limits
description: Per-user usage-vs-cap reporting and account-wide at-limit counts.
paths:
/api/admin/histories/charts/tools:
post:
tags:
- Admin Histories
summary: Get tool usage and prompt cache census
description: >
Aggregate-only census of tool usage and prompt-cache behaviour over
conversation history. The response carries tool names, model names, lane
names, bucket labels and counts. It never carries a user id, a Digital
Twin id, a conversation id, a question or an answer. Distinct users and
twins are returned as counts. One request runs one bounded view. The
window is at most 31 days (a wider window is rejected, never clamped)
and defaults to the last 7 days. Results are cached. An administrator of
one Digital Twin only ever sees that twin. Only real turns are counted -
rows stamped by the turn save path (every saved turn since 2026-09-10)
plus avatar embed sessions. Uploads, sign-in events and other non-turn
history rows are left out. A window that starts before 2026-09-10 is
answered with a warning, because older turns carry no marker. Lanes -
qanda is a single-shot text turn, convo is one Convo Mode (realtime) or
avatar embed session per row, agentic is a turn that ran a conductor,
background workers or a plan execution (its tools are the conductor's
own), and workers (tools view only) counts the tools that the background
workers of a turn ran. A tool that appears only under workers is never
called by a single-shot turn. Labels are vetted - a tool label is a
platform tool name, mcp_bridged or other, and a model label that does
not look like a model name is returned as other. Tools reached through
an MCP connector are counted together as mcp_bridged, because their
stored name carries the connector label chosen by the customer. The
twins count treats the personal scope (no twin) as one twin.
Approximations - sameSlotTurns counts turns that share a clock-aligned
five-minute slot with an earlier turn of the same conversation, which is
a lower bound on follow-ups that land inside a five-minute prompt cache.
A conversation is a user, a twin and a course_id, and a row without
course_id counts as its own conversation.
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
view:
type: string
enum:
- tools
- turns
- models
- conversations
default: tools
description: >
tools - calls, turns, successes, MCP calls, distinct users
and twins per tool and lane. turns - how many turns make 0,
1, 2, 3, 4 or 5+ tool calls per lane, with token sums.
models - turns, turns with tools, cold turns, cache reads
and writes per model and lane. conversations - conversation
size buckets, tool use, first tool use, and distinct tools
per tool-using conversation (text lanes only).
lane:
type: string
enum:
- all
- qanda
- convo
- agentic
- workers
default: all
description: >
Restrict to one lane. The conversations view does not accept
convo. The workers lane exists only in the tools view. In
the tools view, all returns the turn-level rows and the
workers rows.
model:
type: string
maxLength: 200
description: Exact conversation model name to restrict to
institution:
type: string
description: >
Space-separated institution IDs to filter (institution is
the API word for a Digital Twin). Must be a string - any
other type is rejected.
account:
type: string
description: Space-separated account IDs to filter. Must be a string.
daterange:
type: array
items:
type: string
format: date
minItems: 2
maxItems: 2
description: >-
Start and end day, inclusive, in UTC. At most 31 days.
Defaults to the last 7 days.
top:
type: integer
minimum: 1
maximum: 500
default: 200
description: Maximum rows for the tools view, ordered by calls
responses:
'200':
description: Census for the requested view
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
view:
type: string
lane:
type: string
model:
type: string
nullable: true
window:
type: object
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
days:
type: integer
turnMarkerSince:
type: string
format: date
description: >-
First day whose turns carry the turn marker. Earlier
turns are not counted.
truncated:
type: boolean
description: >-
True when the tools view (top) or the models view (60
rows) had more rows than returned
warnings:
type: array
items:
type: string
rows:
description: >
An array of rows for the tools, turns and models
views. For the conversations view, an object with two
arrays, buckets and distinctTools. tools row - tool,
lane, calls, ok, mcpCalls, turns, users, twins. turns
row - lane, toolCalls (5 means 5 or more), turns,
usage, cached, cacheWrite, conductorTokens. models row
- model, lane, turns, turnsWithTools, coldTurns (no
cache read), writeTurns (paid a cache write), usage,
cached, cacheWrite, completion, conductorTokens. On an
agentic turn usage is the answering model only, while
cached and cacheWrite also include the conductor, so
add conductorTokens to usage before comparing them.
buckets row - size (1, 2, 3-5, 6+), usesTools,
firstToolOnFirstTurn, startedInWindow (1 when the
conversation began inside the window, so it is
complete), conversations, turns, toolTurns,
sameSlotTurns. distinctTools row - distinctTools (5
means 5 or more), conversations.
oneOf:
- type: array
items:
type: object
additionalProperties: true
- type: object
properties:
buckets:
type: array
items:
type: object
additionalProperties: true
distinctTools:
type: array
items:
type: object
additionalProperties: true
'400':
description: >-
Unknown view or lane, a lane that the view does not accept, an
invalid or too wide date range, a scope value that is not a string,
a refused access check, or a failed query
'401':
description: Unauthorized
'403':
description: >-
Admin access required, or the caller is not a super admin and no
Digital Twin scope applies
'408':
description: >-
The query hit its time ceiling. Narrow the date range, the Digital
Twin or the lane.
'429':
description: >-
Another uncached census is already running on this server. Retry in
a few seconds.
security:
- apiKeyAuth: []
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-access-token
description: JWT token passed in x-access-token header
````