ModulesAI ModuleAPIsTelemetry Usage

Telemetry Usage API

The AI Application Programming Interface serves as the central artery for your AI analytics. By transmitting strict payloads conforming to our telemetry schema, Antarctica computes your infrastructure intelligence entirely off the main thread.

POST https://otm-api.antarctica.io/v1/telemetry/usage

Request Schema

The request payload relies on a robust Joi validation schema. It employs strict typing to preserve clean analytics. Requests failing to accurately represent the types mapped below will emit an HTTP 400 Validation Error.

1. Request Object (request) — Object, Required

FieldTypeConstraintDescription
modelIdstringRequiredMachine identifier of the LLM. Ex: "gpt-4-turbo" or "claude-3-opus-20240229".
statusstringRequiredDefines the execution outcome. Strict enum: "success" or "error".
providerstringRequiredCorporate provider underlying the execution. Ex: "openai", "anthropic", "google".

2. User Object (user) — Object, Required

FieldTypeConstraintDescription
idstringRequiredUnique, persistent identity tied to the interaction (UUID / account hash).
typestringRequiredDefines origin bounds. Strict enum: "external" (B2B/B2C users) or "internal" (Employee use).
namestringOptionalHuman-readable alias corresponding to the invoking identity.

3. Tokens Object (tokens) — Object, Conditionally Required

Note: Required if the request.status evaluates to "success".

FieldTypeConstraintDescription
inputuintRequiredThe absolute number of parsed prompt tokens sent to the LLM.
outputuintRequiredThe absolute number of completion tokens streamed from the LLM.
totaluintOptionalConvenience integer defining the combined metric.

4. Timing Object (timing) — Object, Conditionally Required

Note: Required if the request.status evaluates to "success".

FieldTypeConstraintDescription
startTimeISO 8601RequiredPrecise timestamp of the initial outward TCP request.
firstTokenTimeISO 8601RequiredTiming marker denoting the reception of the first viable chunk (TTFT).
lastTokenTimeISO 8601RequiredTimestamp capturing the exact moment the connection was closed fully resolved.
latencyMsuintOptionalComplete lifecycle duration measured in milliseconds.

5. Supplemental Structures

  • error object (Required when status = "error")
    code (string)
    message (string)
    stack (string, optional)

  • io object (Optional): Includes the literal string mapping of the prompt and response. Only provide this if local compliance permits logging raw inputs!

  • context object (Optional): Accepts an unconstrained dictionary for freeform tagging, e.g., {"projectId": "prj_xxxx", "location": "eu-west-1"}.

JSON Payload Examples

Sometimes it is easiest to just see the raw data. Below are complete, formatted JSON payloads you can use as templates for your system.

1. Successful Inference

When your LLM generates a successful response, send the complete tokens and timing metrics:

{
  "request": {
    "modelId": "gpt-4-turbo",
    "status": "success",
    "provider": "openai"
  },
  "user": {
    "id": "usr_9a8b7c6d",
    "type": "external",
    "name": "Jane Doe"
  },
  "tokens": {
    "input": 145,
    "output": 810,
    "total": 955
  },
  "timing": {
    "startTime": "2024-05-18T14:30:00.000Z",
    "firstTokenTime": "2024-05-18T14:30:01.200Z",
    "lastTokenTime": "2024-05-18T14:30:05.400Z",
    "latencyMs": 5400
  },
  "io": {
    "prompt": "Write a python script to reverse a string.",
    "response": "Here is your python script..."
  },
  "context": {
    "projectId": "prj_python_tutor",
    "location": "us-east-1"
  }
}

2. Failed Inference (System Error)

If the prompt was flagged, or the provider API timed out, you do not send tokens or timing. Instead, pass the error details:

{
  "request": {
    "modelId": "claude-3-opus",
    "status": "error",
    "provider": "anthropic"
  },
  "user": {
    "id": "usr_1x2y3z",
    "type": "internal"
  },
  "error": {
    "code": "provider_timeout",
    "message": "Anthropic API failed to respond within 30 seconds.",
    "stack": "Error: timeout at Object.request..."
  },
  "context": {
    "projectId": "internal_testing"
  }
}

Production Implementations

Below are battle-hardened integration strategies. Note the usage of UUIDs for Idempotency boundaries and non-blocking asynchronous event architectures preventing telemetry dispatch from bogging down runtime.

import crypto from "crypto";
 
/**
 * Dispatch Telemetry cleanly and asynchronously without blocking the main event loops.
 */
async function dispatchTelemetryAnalytics(completionMetrics) {
  const payload = {
    request: {
      modelId: "gpt-4-turbo",
      status: "success",
      provider: "openai",
    },
    user: { id: "user_a1b2c3", type: "external" },
    tokens: {
      input: completionMetrics.prompt_tokens,
      output: completionMetrics.completion_tokens,
    },
    timing: {
      startTime: completionMetrics.time.start,
      firstTokenTime: completionMetrics.time.ttft,
      lastTokenTime: completionMetrics.time.end,
    },
    context: {
      projectId: "internal_marketing_gen",
      location: "us-east-1",
    },
  };
 
  try {
    // Run un-awaited to execute purely in background/edge runtime
    fetch("https://otm-api.antarctica.io/v1/telemetry/usage", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.ANTARCTICA_SK_PROD}`,
        "Content-Type": "application/json",
        "Idempotency-Key": crypto.randomUUID(), // Crucial for enterprise reliability
      },
      body: JSON.stringify(payload),
      // Set an aggressive timeout to ensure thread release
      signal: AbortSignal.timeout(3000),
    }).catch((err) =>
      console.warn("[Analytics Warning] Dropped package:", err),
    );
  } catch (err) {
    // Ensures your primary application completely ignores reporting crashes
    console.error("Critical parsing error during telemetry generation", err);
  }
}
Rate LimitingSecurity