Skip to content

Audit and history

Method & path Scope Notes
GET /organizations/:id/history records:read Audit events of one record, newest first, cursor list
GET /contacts/:id/history records:read
GET /deals/:id/history records:read
GET /audit-events audit:read The whole account. entityType, entityId, actorType, actorId, limit, cursor
{
"id": "…",
"occurredAt": "2026-11-15T09:30:00.000Z",
"actor": { "type": "agent", "id": "…", "name": "Nana" },
"surface": "mcp",
"action": "updated",
"entityType": "contact",
"entityId": "…",
"changes": { "lifecycle": { "from": "lead", "to": "prospect" } },
"requestId": "…",
"agentRun": "gmail-import-2026-11-15",
"idempotencyKey": "gmail:THREAD_ID:contacts"
}
  • surface: app (a person in the web app), api (REST with a key), mcp, system (the CLI).
  • action: created, updated, archived, deleted, moved, linked, unlinked, …
  • agentRun is your Mety-Agent-Run header. Send one id per run so a person can see everything a run did.
  • Every write records exactly one event in the same transaction. Derived values (freshness, renumbered board positions) are not audited separately. Long text is summarised ([text, N characters]). A hard delete keeps the field names but not personal values. Nobody can edit or delete audit events.
Terminal window
# what did my agent change today?
curl -s "https://api.mety.ai/api/v1/audit-events?actorType=agent&actorId=$AGENT_ID&limit=100" \
-H "Authorization: Bearer $METY_KEY"
# who touched this deal?
curl -s "https://api.mety.ai/api/v1/deals/$DEAL_ID/history" -H "Authorization: Bearer $METY_KEY"

Read a record’s history before you overwrite a value someone else set. Over MCP: get_history and list_audit_events (the latter only listed with audit:read).