Log a model call or event (POST /api/v1/ingest)

event_id is the idempotency key. Reuse it on retries. When an event with this event_id is already stored, the API answers 409 with reason: replay_detected; treat that as success on a retry (the official SDKs do). A retry of an attempt that was not stored is accepted.
timestamp must be an ISO 8601 date-time no older than 5 minutes.
input and output are limited to 32,000 characters each.
Send the masked text you actually sent to the model, never the original.

Authentication

Send one of these headers (either is accepted):

x-agentid-api-key: <API key>: AgentID API key of the AI system, for example x-agentid-api-key: sk_live_....
Authorization: Bearer <API key>: The same API key passed as Authorization: Bearer sk_live_....

Request body

application/jsonrequiredIngestRequest

event_idstring<uuid>required

Idempotency key. Use the client_event_id of the Guard check.

inputstringrequired

The (masked) prompt sent to the model.

max length 32000

outputstringrequired

The model output.

max length 32000

modelstringrequired

timestampstring<date-time>required

When the event happened; at most 5 minutes old.

system_idstring<uuid>

Optional; must match the API key's system when present.

usageobject

Provider usage object, used for token and cost analytics.

›Show child attributes

prompt_tokensinteger

min 0

completion_tokensinteger

min 0

total_tokensinteger

min 0

prompt_tokens_detailsobject

›Show child attributes

cached_tokensinteger: min 0

Additional properties are accepted.

completion_tokens_detailsobject

›Show child attributes

reasoning_tokensinteger: min 0

Additional properties are accepted.

tokensobject

Normalized token counters, an alternative to usage.

›Show child attributes

inputinteger: min 0
outputinteger: min 0
totalinteger: min 0

Additional properties are accepted.

latencyinteger

End-to-end latency in milliseconds.

min 0

user_idstring

min length 1 · max length 128

request_identityobject

Optional client-side identity hints stored with the event for audit.

›Show child attributes

ip_addressstring
user_agentstring
geostring: Country or region hint.
session_idstring

Additional properties are accepted.

client_capabilitiesobject

Optional description of the calling client. Official SDKs fill it automatically.

›Show child attributes

frameworkstring
pii_masking_enabledboolean: Whether the client masks personal data locally before calling Guard.
secret_masking_enabledboolean: Whether the client masks secrets locally before calling Guard.
has_feedback_handlerboolean
sdk_versionstring

Additional properties are accepted.

metadataobject

Free-form metadata stored with the event. Do not put original sensitive values here.

›Show child attributes

client_event_idstring<uuid>
guard_event_idstring<uuid>
sdk_versionstring

Additional properties are accepted.

event_typestring

One of: start, complete, error, human_override, security_alert, security_block, security_policy_violation, transparency_badge_rendered

severitystring

One of: info, warning, error, high

Example request

curl -X POST "https://app.getagentid.com/api/v1/ingest" \
  -H "x-agentid-api-key: $AGENTID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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",
  "user_id": "user-123",
  "metadata": {
    "client_event_id": "0467f78f-5821-4827-a09b-d59a9b08866c",
    "guard_event_id": "9c1d1b8e-3f5a-4c8e-9a51-0f4f2e5c7d10"
  }
}'

const response = await fetch("https://app.getagentid.com/api/v1/ingest", {
  method: "POST",
  headers: {
    "x-agentid-api-key": process.env.AGENTID_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "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",
    "user_id": "user-123",
    "metadata": {
      "client_event_id": "0467f78f-5821-4827-a09b-d59a9b08866c",
      "guard_event_id": "9c1d1b8e-3f5a-4c8e-9a51-0f4f2e5c7d10"
    }
  }),
});

if (!response.ok) throw new Error(`AgentID request failed: ${response.status}`);
const data = await response.json();

import os
import requests

response = requests.post(
    "https://app.getagentid.com/api/v1/ingest",
    headers={"x-agentid-api-key": os.environ["AGENTID_API_KEY"]},
    json={
        "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",
        "user_id": "user-123",
        "metadata": {
            "client_event_id": "0467f78f-5821-4827-a09b-d59a9b08866c",
            "guard_event_id": "9c1d1b8e-3f5a-4c8e-9a51-0f4f2e5c7d10",
        },
    },
    timeout=10,
)
response.raise_for_status()
data = response.json()

Responses

200Event stored.

›Response schemaIngestSuccessResponse

successbooleanrequired: Value: true
event_idstring<uuid>: Id of the stored event.
reasonstring: Present when a fail-open system accepted the request without storing it fully.
bypassedboolean

Additional properties are accepted.

{
  "success": true,
  "event_id": "285d12c7-7f10-40f2-b50b-e61eb8cfd970"
}

400Invalid JSON, schema validation error, or a stale or invalid `timestamp`.

›Response schemaSimpleErrorResponse

errorstringrequired
reasonstring
detailsany: Validation details or a short diagnostic.

Additional properties are accepted.

{
  "error": "Invalid payload",
  "details": {
    "fieldErrors": {
      "event_id": [
        "Required"
      ]
    }
  }
}

{
  "error": "stale_event_timestamp"
}

401Missing, invalid or revoked API key, or a `system_id` that does not match the key.

›Response schemaSimpleErrorResponse

errorstringrequired
reasonstring
detailsany: Validation details or a short diagnostic.

Additional properties are accepted.

{
  "error": "Unauthorized"
}

403The AI system is suspended (kill switch) or the request was rejected by policy.

›Response schemaSimpleErrorResponse

errorstringrequired
reasonstring
detailsany: Validation details or a short diagnostic.

Additional properties are accepted.

{
  "error": "Access denied: AI system suspended (Kill Switch active)."
}

409An event with this `event_id` is already stored. On a retry, treat it as success.

›Response schemaSimpleErrorResponse

errorstringrequired
reasonstring
detailsany: Validation details or a short diagnostic.

Additional properties are accepted.

{
  "error": "Duplicate event_id",
  "reason": "replay_detected"
}

413Request body exceeds 4 MiB.

›Response schemaSimpleErrorResponse

errorstringrequired
reasonstring
detailsany: Validation details or a short diagnostic.

Additional properties are accepted.

{
  "error": "Payload Too Large"
}

429Rate limit or daily cap exceeded.

Headers

Retry-Afterinteger: Seconds to wait before retrying.
min 1
X-RateLimit-Limitinteger: Maximum requests allowed in the current window.
X-RateLimit-Remaininginteger: Requests remaining in the current window.

›Response schemaSimpleErrorResponse

errorstringrequired
reasonstring
detailsany: Validation details or a short diagnostic.

Additional properties are accepted.

{
  "error": "Rate limit exceeded for this AI system."
}

500Internal processing failure.

›Response schemaSimpleErrorResponse

errorstringrequired
reasonstring
detailsany: Validation details or a short diagnostic.

Additional properties are accepted.

{
  "error": "Internal server error"
}

503A dependency is temporarily unavailable. Retry with backoff.

›Response schemaSimpleErrorResponse

errorstringrequired
reasonstring
detailsany: Validation details or a short diagnostic.

Additional properties are accepted.

{
  "error": "Database dependency unavailable.",
  "reason": "system_failure_db_unavailable"
}