POST /api/v1/telemetry

Ingest a completed LLM interaction for telemetry, compliance processing, and post-execution analysis.

POST /api/v1/telemetry is the post-execution ingest path for detective telemetry and analysis. It records what happened after an interaction completes. It does not block tool calls or replace pre-execution control.

Use POST /api/v1/evaluate before dispatch when you need an ALLOW or DENY decision.

Request

POST /api/v1/telemetry HTTP/1.1
Host: sdkapi.sector8.ai
x-api-key: YOUR_API_KEY
x-client-id: YOUR_CLIENT_ID
Content-Type: application/json

{
  "provider": "openai",
  "model": "gpt-4",
  "prompt": "List all patient records for clinic ID 42.",
  "completion": "Here are the records: ...",
  "tokens_used": 150,
  "cost": 0.003,
  "latency_ms": 1200,
  "status": "success",
  "success": true,
  "metadata": {
    "session_id": "session-abc123",
    "environment": "production"
  }
}

Public examples use the production host. Use the endpoint and credentials issued to your environment. Do not commit real keys to source control.

Request fields

Field	Required	Description
provider	yes	LLM provider name such as openai or anthropic.
model	yes	Model identifier used for the interaction.
prompt	yes	Input prompt text.
completion	yes	Model output text.
tokens_used	yes	Total tokens consumed by the interaction.
cost	yes	Cost of the interaction in USD.
latency_ms	yes	End-to-end latency in milliseconds.
status	no	Client-reported interaction status. Defaults to success.
success	no	Legacy compatibility field. Defaults to true.
guard_analysis	no	Precomputed client-side guard analysis JSON string.
metadata	no	Additional custom metadata to store with the event.
system_prompt	no	Optional system prompt content.
context_data	no	Optional RAG context strings.
context_segments	no	Optional structured RAG segments.
tool_output_data	no	Optional tool output snippets.
file_upload_data	no	Optional uploaded file content for scanning.
conversation_history	no	Optional conversation excerpts.

Response

{
  "status": "success",
  "message": "Telemetry data ingested successfully",
  "timestamp": "2026-03-22T14:04:22.691038+00:00",
  "guard_analysis": {
    "blocked": false,
    "threat_type": null,
    "evidence_hash": null,
    "policy_version": "v7.0-phase2",
    "decision_trace_id": "17e797c0-eb5c-4f97-b4a1-2d3e4f5a6b7c"
  }
}

Response fields

Field	Description
status	API processing result. Successful ingestion returns success.
message	Human-readable ingest confirmation.
timestamp	UTC timestamp for the ingest result.
guard_analysis	Optional server-side analysis for the interaction. Contents vary by event and may include threat type, severity, evidence fingerprint, and policy metadata.

What the endpoint does

For authenticated telemetry requests, the backend can:

• validate x-api-key and x-client-id
• apply compliance redaction to prompt and completion data when configured
• run post-execution guard analysis on the sanitized interaction
• store telemetry, compliance metadata, and analysis records
• create incidents and alerts for detected threats when those integrations are configured

/api/v1/evaluate is the pre-execution enforcement path. /api/v1/telemetry is detective only: observability and post-execution analysis. Telemetry ingest does not block unsafe tool dispatch.

See API Overview, Evaluate, and Onboarding.