vikia Public documentation FR Dashboard

FOR COLLECTORS AND AI AGENTS

Send metrics to Vikia

This page can be shared and read without an account or JavaScript. It covers ingestion only; it contains no keys or private data.

1. Essential contract

POST https://vikia.lafougere.dev/api/metrics
Content-Type: application/json
Authorization: Bearer <VIKIA_API_KEY>

The examples below are illustrative, not actual provider prices. Submitting them really adds metrics: there is no dry-run mode or deletion through the API. Do not submit fake data to “test” production.

2. Record fields

All fields are required except event_id, which is strongly recommended. Names are case-sensitive; any unknown field is rejected.

JSON types, constraints and meaning of each field
FieldJSON typeRule
event_idoptional string1 to 160 printable characters. Unique identifier across the entire instance, not just per provider. Example: source + period + provider + model + currency + price version.
datestringRFC3339 timestamp with a time zone, for example 2026-11-16T12:00:00Z or 2026-11-16T13:00:00+01:00. A YYYY-MM-DD date means midnight UTC. Use a consistent convention, such as the end of the period.
providerstring1 to 120 printable characters. Provider name, kept as supplied.
modelstring1 to 180 printable characters. Identifier of the model actually used.
currencystringExactly EUR or USD. Both prices use this same currency. Original amounts are preserved; do not convert records before submitting them.
input_price_per_milliondecimal stringPrice of one million input tokens, from "0" to "1000000000", with up to 9 decimal places.
output_price_per_milliondecimal stringThe same constraints, for output tokens.
input_tokensintegerFrom 0 to 1000000000000000 inclusive. Input tokens for this record.
output_tokensintegerThe same bounds. Output tokens for this record.
requestsintegerThe same bounds. Number of calls for this record, not the number of HTTP requests sent to Vikia.

Valid prices: "0", "0.15", "0.000000001". Invalid prices: 0.15 (a number instead of a string), "1e-3", "0,15", "-1". Counters must be JSON integers, not strings, floats or booleans. No null, NaN, Infinity or duplicate JSON members.

Dates are normalized to UTC with microsecond precision; finer precision is truncated. The dashboard displays these timestamps in Paris time (Europe/Paris), with automatic daylight-saving time changes. Storage, the API and filter bounds remain in UTC. Timestamps without a time zone and leap seconds :60 are not allowed. Control characters are forbidden in identifiers and names. Future records are accepted but only appear in aggregates once their date has passed.

Spending precision

cost = (input_price_per_million × input_tokens
      + output_price_per_million × output_tokens) / 1000000

The server calculates and stores this amount exactly, without monetary floating-point arithmetic. Do not send a cost field: it would be rejected. EUR and USD totals remain separate. The dashboard also displays an approximate total in euros: the EUR total + the USD total converted at the latest ECB reference rate. This public rate is checked in the background every 3 hours, with no key or subscription. It is generally published on business days; it is neither a real-time exchange rate nor a historical conversion. The last known rate is retained during an outage and flagged as stale. If no rate is available, USD conversion is shown as unavailable. No additional fields need to be sent. This is an estimate at the supplied price, not an invoice: discounts, taxes, caching or special billing are not inferred automatically. If the price or usage is unknown, resolve that information before submitting; do not invent prices or replace an unknown value with zero.

3. Submission examples

A single record

Save this format in metric.json, replacing the illustrative values with real ones:

{
  "event_id": "exemple-collecteur:2026-11-16T12:00:00Z:modele-exemple:USD",
  "date": "2026-11-16T12:00:00Z",
  "provider": "Fournisseur exemple",
  "model": "modele-exemple",
  "currency": "USD",
  "input_price_per_million": "0.150000000",
  "output_price_per_million": "0.600000000",
  "input_tokens": 12000,
  "output_tokens": 2500,
  "requests": 8
}

cURL

Provide VIKIA_API_KEY through the collector’s secure environment, without hardcoding it, displaying it or writing it to logs. The file must already contain a validated real record.

curl --silent --show-error --fail-with-body \
  --connect-timeout 5 --max-time 30 \
  --request POST 'https://vikia.lafougere.dev/api/metrics' \
  --header "Authorization: Bearer ${VIKIA_API_KEY:?Missing ingestion key}" \
  --header 'Content-Type: application/json' \
  --data-binary @metric.json

Python, without additional libraries

This example makes a single submission and preserves error codes. The retry strategy is described below; the file and its identifier must remain unchanged if the outcome is uncertain.

import json
import os
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen

request = Request(
    "https://vikia.lafougere.dev/api/metrics",
    data=Path("metric.json").read_bytes(),
    headers={
        "Authorization": "Bearer " + os.environ["VIKIA_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urlopen(request, timeout=30) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print("HTTP", error.code, "Retry-After:", error.headers.get("Retry-After"))
    print(error.read().decode("utf-8", errors="replace"))
    raise SystemExit(1)
except (URLError, TimeoutError):
    raise SystemExit("Uncertain outcome: keep the same record for retrying.")

Multiple records in one request

A batch contains 1 to 500 records in a {"metrics": [...]} object, never a bare array. Do not add any other root-level field. Send the batch file using the same method and headers.

{
  "metrics": [
    {
      "event_id": "exemple-lot:2026-11-16:modele-a:USD",
      "date": "2026-11-16",
      "provider": "Fournisseur exemple",
      "model": "modele-a",
      "currency": "USD",
      "input_price_per_million": "0.15",
      "output_price_per_million": "0.60",
      "input_tokens": 1000,
      "output_tokens": 200,
      "requests": 2
    },
    {
      "event_id": "exemple-lot:2026-11-16:modele-b:USD",
      "date": "2026-11-16",
      "provider": "Fournisseur exemple",
      "model": "modele-b",
      "currency": "USD",
      "input_price_per_million": "1.25",
      "output_price_per_million": "5",
      "input_tokens": 500,
      "output_tokens": 100,
      "requests": 1
    }
  ]
}

4. Duplicates, conflicts and retries

Recommended collector strategy

  1. Split usage into non-overlapping periods, with a stable identifier for each record. Save pending records locally before any network call.
  2. On 200 or 201, check the JSON body; inserted + duplicates must match the number of records submitted, then acknowledge the batch locally.
  3. On 429, wait the number of seconds specified by Retry-After, then resubmit the same batch. After a connection loss, timeout or 5xx, the outcome may be uncertain: use increasing delays with jitter and a bounded number of attempts, without changing identifiers or content.
  4. On 400, 401, 409, 413 or 415, stop blind retries and resolve the cause. When splitting an oversized batch, preserve every identifier.

5. Responses and limits

201 : {"inserted": 1, "duplicates": 0}
200 : {"inserted": 0, "duplicates": 1}
409 : {"error": "event_id conflict"}
HTTPMeaningAction
201At least one new record was added.Acknowledge the batch, including any duplicates.
200All records already existed.Treat the batch as received; do not duplicate anything.
400Invalid JSON, fields, formats or value limits.Fix the collector. The JSON body contains an error field.
401Missing or incorrect key.Check the ingestion key and the exact Bearer header format.
405Method not allowed.Use POST, not GET.
409Identifier already associated with different content.Investigate without creating a duplicate. No partial batch additions.
413Body too large.Split the batch; preserve identifiers.
415Non-JSON Content-Type.Use application/json.
429Rate limit reached.Respect Retry-After, expressed in seconds.
5xxServer or proxy error.Potentially uncertain outcome: bounded retries, unchanged identifiers.

Current ingestion limits: 500 records per batch, 1 048 576 bytes (1 MiB) per HTTP body, 120 requests per minute per IP, and a global ceiling of 2 000 requests per minute. Errors and attempts without a key also count toward these limits. A batch of 500 records counts as one request. A batch with too many records is rejected with 400; an oversized body with 413.

The application’s 429 responses include Retry-After, RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (delay in seconds). Application errors are JSON; a proxy rejection may produce text or HTML, so check the Content-Type before decoding an error.

The ingestion key only authorizes writing, not reading the dashboard. History does not expire automatically. The public GET https://vikia.lafougere.dev/healthz check returns {"status":"ok"}; it validates neither the key nor a record. No metrics access is public, and no export or API-key-based read route is provided.

6. API v2: requests and calls

POST https://vikia.lafougere.dev/api/v2/usage — same ingestion Bearer key, HTTPS only, no cookie and no followed redirects. Reads and /usage require a dashboard session; the ingestion key grants no read access.

The body contains exactly {"events": [...]} : 1 to 100 events, 0 to 128 calls per event, at most 12 800 calls and 1 MiB per batch. The quotas and responses above also apply to this route (per route). Errors and unauthenticated attempts count.

Exact required event fields: event_id, application, request_id, date, request_type, status, calls. Nonempty printable identifiers: event_id and request_id ≤160 characters, application ≤120. event_id is globally unique within v2; request_id is unique per application. request_type is message, callback, command or system; status is success, error or cancelled.

Exact required call fields: call_id, date, provider, model, currency, input_tokens, output_tokens, cost, cost_source, status, input_price_per_million, output_price_per_million. call_id is unique per application (≤160 characters), provider ≤120, model ≤180, all nonempty and printable. currency is EUR or USD; status is success, error or unknown. Each actual model HTTP attempt is one call, including a billed failed attempt, never a Telegram message.

Illustrative example only; never submit it to production:

{
  "events": [{
    "event_id": "example-v2-event",
    "application": "example-app",
    "request_id": "example-v2-request",
    "date": "2026-11-16T11:00:00Z",
    "request_type": "message",
    "status": "error",
    "calls": [{
      "call_id": "example-v2-call",
      "date": "2026-11-16T11:00:01Z",
      "provider": "Example provider",
      "model": "example-model",
      "currency": "USD",
      "input_tokens": null,
      "output_tokens": null,
      "cost": null,
      "cost_source": "unavailable",
      "status": "unknown",
      "input_price_per_million": null,
      "output_price_per_million": null
    }]
  }]
}

Persist identifiers and content before the first upload. Same event and normalized content (dates, decimals, call order): duplicate. Changed event_id content, an application/request_id collision or application/call_id collision returns 409 and rolls back the entire batch. On 200/201, verify inserted + duplicates = event count before acknowledging locally; on uncertain failure, retry the same batch.

Compatibility and private reads

/api/metrics and v1 totals remain unchanged: unattributed historical estimates only. Do not submit the same usage to both versions. No actual historical spending or n8n costs are reconstructed or imported. /usage separately presents v2 requests, filterable by application, and provider/model details for each attempt, with distinct reported, estimated and unavailable amounts. V1 totals are never added to v2 totals, nor EUR to USD. Display conversions never change native amounts.

Session-authenticated reads: GET /api/v2/dashboard?range=30d&application=example-app, GET /api/v2/requests?range=all&limit=50&offset=0, GET /api/v2/request?event_id=example-v2-event. Ranges: 24h, 7d, 30d, month, year, all; UTC bounds, exclusive end. limit 1..100, offset 0..10^9. Costs and usage counters are exact strings in read responses; null remains unknown in calls. Data is never public.