Skip to content
AgentIDDocs

Type at least two characters to search titles, headings and content.

↑ ↓ to navigate↵ to open
AgentID Docs

SDKs & API

Ingest API guide

Log completed model calls and workflow events with POST /api/v1/ingest so they appear in the activity log with tokens and cost.

POSThttps://app.getagentid.com/api/v1/ingestReference

Log a model call or event

After the model answers, log the call so the activity log shows the answer, and token and cost dashboards have data. Full schema: API reference.

Request

{
  "event_id": "0467f78f-5821-4827-a09b-d59a9b08866c",
  "system_id": "cf84f936-95bc-45a4-bf98-9a1a16bf29c9",
  "input": "Write a reply to <PERSON_NAME_1> (<EMAIL_1>) about her refund.",
  "output": "Dear <PERSON_NAME_1>, your refund has been approved.",
  "model": "gpt-4o-mini",
  "usage": { "prompt_tokens": 33, "completion_tokens": 12, "total_tokens": 45 },
  "latency": 1450,
  "event_type": "complete",
  "severity": "info",
  "timestamp": "2026-10-14T09:30:00Z",
  "metadata": {
    "client_event_id": "0467f78f-5821-4827-a09b-d59a9b08866c",
    "guard_event_id": "9c1d1b8e-3f5a-4c8e-9a51-0f4f2e5c7d10"
  }
}
event_iduuidrequired

Idempotency key. Use the client_event_id of the Guard check.

inputstring (max 32,000 chars)required

The masked prompt you sent to the model.

outputstring (max 32,000 chars)required

The model's answer.

modelstringrequired

Model id, used for cost calculation.

timestampISO 8601 date-timerequired

When the call happened; at most 5 minutes old.

system_iduuid

Must match the key's system when present.

usageobject

Provider usage (prompt_tokens, completion_tokens, total_tokens).

tokensobject

Alternative normalized counters (input, output, total).

latencyinteger (ms)

End-to-end latency.

event_typeenum

start, complete, error, human_override, security_alert, security_block, security_policy_violation, transparency_badge_rendered.

severity"info" | "warning" | "error" | "high"

Event severity.

user_idstring

Your end-user identifier.

metadataobject

Free-form; include client_event_id and guard_event_id to link the Guard check.

Linking guard and answer

Use the same id for the Guard check and the log: send it as client_event_id to Guard and as event_id (and metadata.client_event_id) to ingest. The activity log then shows one row that moves from Prompt checked to Complete.

Tokens and cost

Total Spend, token charts and ROI are computed from completion events that include a model id and usage (or tokens). Without them the event still appears in the activity log, but cost stays empty. ROI also needs the business context of the system (human hourly rate and time per task).

Rules

  • Log masked text. Log the protected text you sent to the provider, never the original. Logging a masked copy does not protect a model call that already received raw data.
  • Fresh timestamps. Events older than 5 minutes are rejected with 400 (stale_event_timestamp).
  • Retries. Reuse the same event_id. If the event is already stored, the API answers 409 with reason: replay_detected; treat it as success.
  • Size. input and output are limited to 32,000 characters each; the body to 4 MiB.

Workflow and tool events

For agent runs, log each tool call or operational step as its own event and group them with a shared workflow run id. The SDKs provide logOperation() and a workflow trail helper for this; see Node.js SDK. Non-model events show Model: Not applicable and do not count toward spend.

Finalize (optional)

POSThttps://app.getagentid.com/api/v1/ingest/finalizeReference

Attach SDK ingest timing

The official SDKs call /api/v1/ingest/finalize after a successful ingest to attach their measured ingest time (sdk_ingest_ms) to the same event. It changes no content and is safe to repeat. You do not need it for a custom integration. See API reference.