API Reference

Track Usage

Ingest a normalized AI usage event. This endpoint accepts only Tallyify API keys and privacy-safe aggregate usage metrics.

Endpoint

POST/v1/track

Authentication

Required. Pass your Tallyify API key (scope track:write) as a Bearer token:

Shell
Authorization: Bearer tly_live_yourkey

Request Body

Field	Type	Required	Description
`provider`	`string`	Yes	Provider slug such as `openai`, `anthropic`, `google`.
`model`	`string`	No	Provider model name.
`input_tokens`	`number`	No	Prompt/input tokens.
`output_tokens`	`number`	No	Completion/output tokens.
`total_tokens`	`number`	No	Total tokens. If omitted, input + output is used.
`metadata`	`object`	No	Primitive labels such as feature or environment.

Privacy Rules

Provider API keys must never be sent to Tallyify. Payloads containing values like sk-proj-, provider key environment variables, provider bearer tokens, prompts, messages or responses are rejected.

Response

201 Created - Event ingested successfully.

JSON
{ "success": true, "processed": true }

Code Examples

TypeScript
import { Tracker } from '@tallyify/sdk';
import OpenAI from 'openai';

const tracker = new Tracker({ apiKey: process.env.TALLYIFY_API_KEY });
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const result = await tracker.track(
  openai.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'Hello!' }]
  }),
  {
    provider: 'openai',
    model: 'gpt-4o-mini',
    metadata: { feature: 'chatbot', environment: 'production' }
  }
);