AI usage data specification

Velatir gives organisations a single view of how AI is used across their business: oversight, compliance, and insight. To include your product in that view, Velatir connects to your system and retrieves a defined set of data describing how their people use its AI features. This specification defines the data Velatir consumes and the shape it expects. The transport is your choice; the data model is what is normative.

Access is strictly read-only. Velatir retrieves data on a schedule and never sits in the path of a live request, so an integration cannot affect your users’ experience.

Resources

Velatir consumes four independent resource types. Implement those your system supports; apart from identifiers and timestamps, all fields are optional.

1. Conversations

One record per AI interaction: a conversation, or a single request and response exchange for stateless systems. This is the content Velatir’s compliance agents review.

string

Stable, unique identifier for the interaction.

string

Thread identifier, where the interaction is part of a multi-turn conversation.

timestamp

When the interaction began. RFC 3339, UTC.

timestamp

When the record was last modified.

timestamp

Present when the interaction has been deleted.

object

The person who ran the interaction.

Show user

string

string[]

object

The custom assistant used, if any. See Assistants.

Show assistant

string

Model used, for example gpt-4o.

string

Underlying LLM vendor, for example openai.

object

Sampling configuration: temperature, topP, maxTokens, and similar.

string

The system prompt in effect. Provide systemPromptHash instead where the text cannot be shared.

object[]

The turns of the interaction.

Show message

string

enum

user, assistant, system, or tool.

string

timestamp

object[]

Tools or skills invoked during the interaction.

Show tool

string

object[]

Files exchanged during the interaction.

Show attachment

string

enum

uploaded or generated.

string

object

Token counts and cost: inputTokens, outputTokens, totalTokens, cost.

string

Outcome of the interaction.

object

Any additional provider-specific fields, preserved as received.

2. Usage and cost

Aggregated, time-bucketed usage, for adoption and cost reporting.

timestamp

Start of the bucket.

timestamp

End of the bucket.

enum

hour or day.

object

The grouping keys present in the bucket, any subset of the following.

Show dimensions

string

object

The measured values for the bucket.

Show metrics

integer

number

3. Assistants

Where your product allows customers to configure their own assistants, agents, or custom GPTs, one record per assistant describing its configuration.

string

For example active or archived.

timestamp

object

The user who owns the assistant.

enum

private, team, organisation, or public.

string

Default model.

object

Default sampling configuration.

string

The assistant’s instructions. Provide instructionsHash instead where the text cannot be shared.

object[]

Tools or skills installed on the assistant.

Show skill

string

enum

builtin, mcp, plugin, or function.

object[]

Integrations and data sources connected to the assistant.

Show connector

string

string[]

object[]

Attached knowledge or reference files.

object

Rollup: conversationCount, userCount, lastUsedAt.

4. Events

One record per notable action, forming an audit trail. Your native event type is preserved verbatim; the normalised fields are best-effort.

string

timestamp

string

Your native event type.

object

Who performed the action.

Show actor

enum

user, apiKey, serviceAccount, or system.

string

enum

Authentication, Access, Configuration, DataMovement, ResourceLifecycle, Integration, Policy, or Other.

enum

Created, Updated, Deleted, Enabled, Disabled, Exported, Shared, and similar.

object

What the action affected.

Show target

string

For example an assistant, a skill, or a file.

string

object

The raw event body, preserved as received.

Access and synchronisation

Transport. A read-only REST/JSON API is recommended and the simplest to integrate. An MCP server, a scheduled export, or webhooks are equally acceptable; the resource shapes above are what is normative. Authentication. A single credential (bearer token or API key) per customer, scoped to that customer’s data only. Per-resource scopes, for example read:usage or read:conversations, allow a customer to share usage metrics without exposing conversation content. Synchronisation. Velatir retrieves data by polling on a schedule. The following are recommended rather than required; where they are absent, Velatir performs a full re-pull.

Stable identifiers. A stable id on every record allows Velatir to update records in place rather than duplicate them on re-sync.
Timestamps. RFC 3339, UTC. updatedAt and occurredAt allow Velatir to request only records that changed since the previous poll.
Pagination. Lists that return { data[], hasMore, nextCursor } with an opaque, retry-safe cursor allow Velatir to page through large histories reliably.
Incremental retrieval. Filtering lists by updatedSince (conversations, assistants) and occurredAfter (events) avoids re-reading the full history on each poll.
Forward compatibility. Fields and enum values may be added at any time. Velatir ignores unknown fields and never discards an unrecognised event type.

Reference API

A minimal REST implementation consists of the following read-only endpoints:

GET /usage          ?startAt&endAt&granularity&groupBy
GET /assistants     ?updatedSince&cursor
GET /assistants/{id}
GET /conversations  ?updatedSince&startedAfter&cursor
GET /conversations/{id}
GET /events         ?occurredAfter&category&cursor

An example conversation record:

{
  "id": "conv_8f21a0",
  "conversationId": "thread_5521",
  "startedAt": "2026-07-03T09:15:00Z",
  "updatedAt": "2026-07-03T09:16:12Z",
  "user": { "id": "u_204", "email": "user@company.com", "department": "Operations" },
  "assistant": { "id": "asst_44", "name": "Support Assistant" },
  "model": "gpt-4o",
  "modelProvider": "openai",
  "parameters": { "temperature": 0.4, "maxTokens": 1024 },
  "systemPrompt": "You are a helpful assistant that ...",
  "messages": [
    { "id": "m1", "role": "user", "content": "How do I process this request?", "createdAt": "2026-07-03T09:15:00Z" },
    { "id": "m2", "role": "assistant", "content": "First, you ...", "createdAt": "2026-07-03T09:15:04Z" }
  ],
  "tools": [{ "id": "search", "name": "Knowledge search", "type": "builtin" }],
  "usage": { "inputTokens": 320, "outputTokens": 210, "totalTokens": 530 }
}

Getting Started

Platform

Velatir for Desktop

Browser extension

Connectors

Agents

Sessions & Traces

Insights

For Providers

Security & Privacy

Resources

1. Conversations

2. Usage and cost

3. Assistants

4. Events

Access and synchronisation

Reference API

​Resources

​1. Conversations

​2. Usage and cost

​3. Assistants

​4. Events

​Access and synchronisation

​Reference API

Resources

1. Conversations

2. Usage and cost

3. Assistants

4. Events

Access and synchronisation

Reference API