Integration Guide & API Reference

1. Overview

Send one event after each LLM request. LLMtrack stores usage analytics such as provider, model, tokens, latency, status, and feature metadata for your workspace dashboards.

2. Authentication

The ingest endpoint supports either authentication header. If both are sent, a non-empty Bearer credential takes precedence:

• Authorization: Bearer <LLMTRACK_API_KEY>
• x-api-key: <LLMTRACK_API_KEY>

3. Base URL

https://llm-track.com

4. Ingest endpoint

POST https://llm-track.com/api/ingest

5. Required headers

Content-Type: application/json
Authorization: Bearer <LLMTRACK_API_KEY>
Idempotency-Key: <UNIQUE_EVENT_KEY>

# or
x-api-key: <LLMTRACK_API_KEY>
Idempotency-Key: <UNIQUE_EVENT_KEY>

6. Request body schema

{
  "provider": "openai",
  "model": "gpt-5.6-luna",
  "feature": "chat-completion",
  "customer_id": "customer_123",
  "customer_name": "Example Customer",
  "environment": "production",
  "prompt_tokens": 120,
  "completion_tokens": 80,
  "total_tokens": 200,
  "reasoning_tokens": null,
  "cached_input_tokens": null,
  "cache_write_tokens": null,
  "latency_ms": 842,
  "status": "success",
  "metadata": { "trace_id": "trace_123" }
}

7. Field explanations

The HTTP API uses snake_case field names as shown. The Node SDK accepts camelCase only (promptTokens, completionTokens); the Python SDK accepts snake_case. Passing the wrong casing to an SDK is silently ignored.

• provider and model: required non-empty strings.
• feature: optional feature name; it takes precedence over metadata.feature and defaults to unknown.
• customer_id, customer_name, and environment: optional attribution fields; environment defaults to production.
• All token fields are optional non-negative integers or null, including reasoning and cache token sub-types. When total_tokens is omitted or null, it is computed as prompt + completion + reasoning tokens, with missing parts treated as 0. A token-less event stores 0.
• latency_ms: optional non-negative integer or null.
• status: success, error, timeout, or cancelled; defaults to success.
• metadata: optional arbitrary JSON object whose UTF-8 JSON serialization is at most 8 KB (8192 bytes).
• cost: ignored if supplied; LLMtrack always computes cost server-side.
• Idempotency-Key: optional header for safe retries. Reusing a stored key returns HTTP 200 with { "ok": true, "duplicate": true }, creates no event, and consumes no quota or credits.

8. Example payload

{
  "provider": "openai",
  "model": "gpt-5.6-luna",
  "feature": "chat-completion",
  "customer_id": "customer_123",
  "customer_name": "Example Customer",
  "environment": "production",
  "prompt_tokens": 120,
  "completion_tokens": 80,
  "total_tokens": 200,
  "reasoning_tokens": null,
  "cached_input_tokens": null,
  "cache_write_tokens": null,
  "latency_ms": 842,
  "status": "success",
  "metadata": { "trace_id": "trace_123" }
}

9. JavaScript / Node example

These raw examples work in any language. On Node or Python, the official SDK above handles retries, idempotency, and validation for you.

Use this in your app. Do not expose API keys in frontend production code.

await fetch('https://llm-track.com/api/ingest', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <LLMTRACK_API_KEY>',
    'Idempotency-Key': '<UNIQUE_EVENT_KEY>'
  },
  body: JSON.stringify({
  "provider": "openai",
  "model": "gpt-5.6-luna",
  "feature": "chat-completion",
  "customer_id": "customer_123",
  "customer_name": "Example Customer",
  "environment": "production",
  "prompt_tokens": 120,
  "completion_tokens": 80,
  "total_tokens": 200,
  "reasoning_tokens": null,
  "cached_input_tokens": null,
  "cache_write_tokens": null,
  "latency_ms": 842,
  "status": "success",
  "metadata": { "trace_id": "trace_123" }
})
})

10. PowerShell example

Run this in PowerShell. Do not paste JavaScript into PowerShell.

$headers = @{
  "Content-Type" = "application/json"
  "x-api-key" = "<LLMTRACK_API_KEY>"
  "Idempotency-Key" = "<UNIQUE_EVENT_KEY>"
}
$body = @'
{
  "provider": "openai",
  "model": "gpt-5.6-luna",
  "feature": "chat-completion",
  "customer_id": "customer_123",
  "customer_name": "Example Customer",
  "environment": "production",
  "prompt_tokens": 120,
  "completion_tokens": 80,
  "total_tokens": 200,
  "reasoning_tokens": null,
  "cached_input_tokens": null,
  "cache_write_tokens": null,
  "latency_ms": 842,
  "status": "success",
  "metadata": { "trace_id": "trace_123" }
}
'@
Invoke-RestMethod -Method Post -Uri "https://llm-track.com/api/ingest" -Headers $headers -Body $body

11. curl example

Run this in Command Prompt, a terminal, or a shell that has curl available. Do not paste curl into the browser console.

curl -X POST "https://llm-track.com/api/ingest" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <LLMTRACK_API_KEY>" \
  -H "Idempotency-Key: <UNIQUE_EVENT_KEY>" \
  -d '{
  "provider": "openai",
  "model": "gpt-5.6-luna",
  "feature": "chat-completion",
  "customer_id": "customer_123",
  "customer_name": "Example Customer",
  "environment": "production",
  "prompt_tokens": 120,
  "completion_tokens": 80,
  "total_tokens": 200,
  "reasoning_tokens": null,
  "cached_input_tokens": null,
  "cache_write_tokens": null,
  "latency_ms": 842,
  "status": "success",
  "metadata": { "trace_id": "trace_123" }
}'

12. Python example

import requests

response = requests.post(
    'https://llm-track.com/api/ingest',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': '<LLMTRACK_API_KEY>',
        'Idempotency-Key': '<UNIQUE_EVENT_KEY>',
    },
    json={
  "provider": "openai",
  "model": "gpt-5.6-luna",
  "feature": "chat-completion",
  "customer_id": "customer_123",
  "customer_name": "Example Customer",
  "environment": "production",
  "prompt_tokens": 120,
  "completion_tokens": 80,
  "total_tokens": 200,
  "reasoning_tokens": None,
  "cached_input_tokens": None,
  "cache_write_tokens": None,
  "latency_ms": 842,
  "status": "success",
  "metadata": { "trace_id": "trace_123" }
},
    timeout=10,
)
print(response.status_code, response.json())

13. Success response

A successful event returns HTTP 200 with duplicate: false. pricing_status: unknown_model means no active pricing row exists, so cost is 0; this is different from a genuine calculated zero. A duplicate idempotency key returns HTTP 200.

{
  "ok": true,
  "duplicate": false,
  "id": "<uuid>",
  "cost": 0.00042,
  "consumption_source": "included",
  "dashboard_visible": true,
  "visibility_reason": null,
  "visibility_context": null,
  "pricing_status": "ok"
}
{ "ok": true, "duplicate": true }

14. Error responses

• 400 Invalid payload: malformed JSON or invalid fields.
• 401 Missing API key or Invalid API key.
• 401 Revoked API key or Inactive API key: deleted/revoked or deactivated keys cannot ingest data.
• 402 Free plan quota exceeded or usage limit responses when plan limits are reached.
• 500 Internal server error: retry later and contact support if it continues.

15. API key safety

Use an LLMtrack ingestion key, not an OpenAI, Anthropic, or other provider key. Keep keys on your server, in secure server-side configuration, or in protected local testing only.

16. Deactivated/deleted key behavior

Deactivated keys return an inactive-key error. Deleted or revoked keys return a revoked or invalid-key error. Create a new key if the raw key is lost or compromised.

17. Dashboard visibility explanation

Accepted events are associated with the workspace attached to the authenticated key.

18. Testing guidance

1. Create or copy an LLMtrack ingestion key from your dashboard.
2. Send the example payload to https://llm-track.com/api/ingest.
3. Use PowerShell, curl, Python, or server-side JavaScript for reliable tests.
4. If a browser console request is blocked by Content Security Policy, test from a terminal instead.

19. Common mistakes

• Using an OpenAI key instead of an LLMtrack key.
• Pasting JavaScript fetch into PowerShell.
• Pasting curl into a browser console.
• Browser console requests being blocked by Content Security Policy.
• Using a deactivated/deleted key.
• Exposing API keys in frontend/client-side production code.