LLMtrack Docs

Practical setup notes for sending LLM usage events to LLMtrack. Do not expose API keys in frontend production code.

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 both authentication headers:

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>

# or
x-api-key: <LLMTRACK_API_KEY>

6. Request body schema

{
  "provider": "openai",
  "model": "gpt-4o-mini",
  "prompt_tokens": 120,
  "completion_tokens": 80,
  "total_tokens": 200,
  "cost": 0.00015,
  "latency_ms": 842,
  "status": "success",
  "metadata": {
    "feature": "chat-completion"
  }
}

7. Field explanations

provider: LLM provider name, such as openai.
model: model used for the request.
prompt_tokens, completion_tokens, total_tokens: token counts. Use null when unavailable.
cost: optional client-side cost value; current ingest processing computes stored cost from token counts and model pricing.
latency_ms: request latency in milliseconds, or null.
status: request status. If omitted, the API defaults to success.
metadata.feature: the feature/function name used in analytics. If omitted, LLMtrack records unknown.

8. Example payload

{
  "provider": "openai",
  "model": "gpt-4o-mini",
  "prompt_tokens": 120,
  "completion_tokens": 80,
  "total_tokens": 200,
  "cost": 0.00015,
  "latency_ms": 842,
  "status": "success",
  "metadata": {
    "feature": "chat-completion"
  }
}

9. JavaScript / Node example

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>'
  },
  body: JSON.stringify({
  "provider": "openai",
  "model": "gpt-4o-mini",
  "prompt_tokens": 120,
  "completion_tokens": 80,
  "total_tokens": 200,
  "cost": 0.00015,
  "latency_ms": 842,
  "status": "success",
  "metadata": {
    "feature": "chat-completion"
  }
})
})

10. PowerShell example

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

$headers = @{
  "Content-Type" = "application/json"
  "x-api-key" = "<LLMTRACK_API_KEY>"
}
$body = @'
{
  "provider": "openai",
  "model": "gpt-4o-mini",
  "prompt_tokens": 120,
  "completion_tokens": 80,
  "total_tokens": 200,
  "cost": 0.00015,
  "latency_ms": 842,
  "status": "success",
  "metadata": {
    "feature": "chat-completion"
  }
}
'@
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>" \
  -d '{
  "provider": "openai",
  "model": "gpt-4o-mini",
  "prompt_tokens": 120,
  "completion_tokens": 80,
  "total_tokens": 200,
  "cost": 0.00015,
  "latency_ms": 842,
  "status": "success",
  "metadata": {
    "feature": "chat-completion"
  }
}'

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>',
    },
    json={
  "provider": "openai",
  "model": "gpt-4o-mini",
  "prompt_tokens": 120,
  "completion_tokens": 80,
  "total_tokens": 200,
  "cost": 0.00015,
  "latency_ms": 842,
  "status": "success",
  "metadata": {
    "feature": "chat-completion"
  }
},
    timeout=10,
)
print(response.status_code, response.json())

13. Success response

A successful event returns HTTP 201 with JSON like:

{ "ok": true, "consumption_source": "included" }

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. Free-plan source visibility behavior

Free-plan users must match their source definition for events to appear in the Free dashboard. If the API key is valid but provider, model, or metadata.feature does not match the key’s source definition, the event can still be accepted but may be hidden from the dashboard. Paid users have unrestricted source visibility according to current product rules.

17. 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.

18. Dashboard visibility explanation

Accepted events are associated with the workspace attached to the authenticated key. Dashboard visibility then follows plan and source visibility rules.

19. Testing guidance

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

20. 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.
Using provider/model/feature values that do not match Free source definitions.
Exposing API keys in frontend/client-side production code.