API reference · Ingest
Attach SDK ingest timing
Adds the SDK-measured duration of the ingest call (sdk_ingest_ms) to an event that is already stored. Official SDKs call it after a successful /api/v1/ingest. It does not change prompts, outputs or masking. Repeating the call is safe; the first stored value is kept. Only sk_live_ keys are accepted.
https://app.getagentid.com/api/v1/ingest/finalizeAuthentication
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/jsonrequiredIngestFinalizeRequest
client_event_idstring<uuid>requiredThe correlation id used for Guard and ingest.
sdk_ingest_msintegerrequiredDuration of the ingest call measured by the client, in milliseconds.
min 0 · max 600000
system_idstring<uuid>Optional system check.
Example request
curl -X POST "https://app.getagentid.com/api/v1/ingest/finalize" \
-H "x-agentid-api-key: $AGENTID_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_event_id": "0467f78f-5821-4827-a09b-d59a9b08866c",
"system_id": "cf84f936-95bc-45a4-bf98-9a1a16bf29c9",
"sdk_ingest_ms": 83
}'const response = await fetch("https://app.getagentid.com/api/v1/ingest/finalize", {
method: "POST",
headers: {
"x-agentid-api-key": process.env.AGENTID_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({
"client_event_id": "0467f78f-5821-4827-a09b-d59a9b08866c",
"system_id": "cf84f936-95bc-45a4-bf98-9a1a16bf29c9",
"sdk_ingest_ms": 83
}),
});
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/finalize",
headers={"x-agentid-api-key": os.environ["AGENTID_API_KEY"]},
json={
"client_event_id": "0467f78f-5821-4827-a09b-d59a9b08866c",
"system_id": "cf84f936-95bc-45a4-bf98-9a1a16bf29c9",
"sdk_ingest_ms": 83,
},
timeout=10,
)
response.raise_for_status()
data = response.json()Responses
200Timing stored (or already stored).
›Response schemaIngestFinalizeResponse
successbooleanrequiredValue:
trueclient_event_idstring<uuid>requiredsdk_ingest_msintegerrequiredmin 0
{
"success": true,
"client_event_id": "0467f78f-5821-4827-a09b-d59a9b08866c",
"sdk_ingest_ms": 83
}400Invalid JSON, schema validation error, or a stale or invalid `timestamp`.
›Response schemaSimpleErrorResponse
errorstringrequiredreasonstringdetailsanyValidation 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
errorstringrequiredreasonstringdetailsanyValidation details or a short diagnostic.
Additional properties are accepted.
{
"error": "Unauthorized"
}404No event with this `client_event_id` exists for the API key's system.
›Response schemaSimpleErrorResponse
errorstringrequiredreasonstringdetailsanyValidation details or a short diagnostic.
Additional properties are accepted.
{
"error": "Event not found",
"reason": "event_not_found"
}500Internal processing failure.
›Response schemaSimpleErrorResponse
errorstringrequiredreasonstringdetailsanyValidation details or a short diagnostic.
Additional properties are accepted.
{
"error": "Internal server error"
}503A dependency is temporarily unavailable. Retry with backoff.
›Response schemaSimpleErrorResponse
errorstringrequiredreasonstringdetailsanyValidation details or a short diagnostic.
Additional properties are accepted.
{
"error": "Database dependency unavailable.",
"reason": "system_failure_db_unavailable"
}