Compliance - Invocations

Query AI invocation records for compliance and audit purposes. Invocations represent individual AI model calls made by users in chat, workflows, app builder, phone agents, or via the API.

List Invocations

Return a paginated list of invocations visible to the caller, ordered by most recent first.

Endpoint

GET /v1/compliance/invocations

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of results to return (1–1000, default: 50).
`cursor`	string	No	Opaque pagination cursor returned by a previous response.
`start`	string	No	ISO 8601 start timestamp (inclusive), e.g. `2026-01-01T00:00:00Z`.
`end`	string	No	ISO 8601 end timestamp (inclusive), e.g. `2026-12-31T23:59:59Z`.
`tenant_id`	string	No	Filter to a specific tenant (e.g. `tenant_abc123`).
`user_id`	string	No	Filter to a specific user (e.g. `user_xyz789`).
`model_name`	string	No	Filter by AI model name (e.g. `gpt-4o`, `claude-3-5-sonnet-20241022`).
`provider`	string	No	Filter by model developer/provider (e.g. `openai`, `anthropic`).
`agent_id`	string	No	Filter by agent UUID.
`source`	string	No	Filter by invocation source. One of: `chat`, `api`, `workflow`, `app_builder`, `phone`.
`search`	string	No	Case-insensitive text search by user email or session/resource name.

Example Query

curl 'https://ai.hatz.ai/v1/compliance/invocations?limit=25&tenant_id=tenant_abc123&source=chat' \
  -H 'X-API-Key: $HATZ_API_KEY'

Response

{
  "data": [
    {
      "invocation_id": "b2c3d4e5-0000-0000-0000-000000000001",
      "session_id": "c3d4e5f6-0000-0000-0000-000000000001",
      "session_name": "Q2 budget analysis",
      "timestamp": "2026-05-15T14:22:00+00:00",
      "source": "chat",
      "tenant": {
        "id": "tenant_abc123",
        "name": "Acme Corporation"
      },
      "user": {
        "id": "user_xyz789",
        "email": "john.doe@acme.com",
        "name": "John Doe"
      },
      "agent": null,
      "api_key": null,
      "models": {
        "requested": "gpt-4o",
        "actual": ["gpt-4o"],
        "providers": ["openai"]
      },
      "features_used": null,
      "workflow_job_id": null,
      "workflow_step_id": null,
      "resource_deleted_at": null,
      "resource_expires_at": null,
      "files": null,
      "content": null
    },
    {
      "invocation_id": "b2c3d4e5-0000-0000-0000-000000000002",
      "session_id": "c3d4e5f6-0000-0000-0000-000000000002",
      "session_name": null,
      "timestamp": "2026-05-15T13:05:00+00:00",
      "source": "workflow",
      "tenant": {
        "id": "tenant_abc123",
        "name": "Acme Corporation"
      },
      "user": {
        "id": "user_abc456",
        "email": "jane.smith@acme.com",
        "name": "Jane Smith"
      },
      "agent": null,
      "api_key": {
        "id": "d4e5f6a7-0000-0000-0000-000000000001"
      },
      "models": {
        "requested": null,
        "actual": ["claude-3-5-sonnet-20241022"],
        "providers": ["anthropic"]
      },
      "features_used": null,
      "workflow_job_id": "e5f6a7b8-0000-0000-0000-000000000001",
      "workflow_step_id": "f6a7b8c9-0000-0000-0000-000000000001",
      "resource_deleted_at": null,
      "resource_expires_at": null,
      "files": null,
      "content": null
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0xNVQxMzowNTowMCswMDowMCIsImlkIjoiYjJjM2Q0ZTUtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAyIn0="
  }
}

Pagination

This endpoint uses cursor-based pagination. To retrieve subsequent pages, pass the next_cursor value from the previous response as the cursor query parameter. Cursors are opaque — do not parse or construct them manually.

Response Fields

Field	Type	Description
`data[].invocation_id`	string	Unique UUID for this invocation.
`data[].session_id`	string\|null	UUID of the chat session, workflow run, or app this invocation belongs to.
`data[].session_name`	string\|null	Human-readable name of the session or resource, if the caller has content access. `null` otherwise.
`data[].timestamp`	string	UTC ISO 8601 timestamp of the invocation.
`data[].source`	string\|null	Invocation origin: `chat`, `api`, `workflow`, `app_builder`, or `phone`.
`data[].tenant`	object\|null	Tenant identity: `id` and `name`.
`data[].user`	object\|null	User identity: `id`, `email`, and `name`. `null` for keyless system calls.
`data[].agent`	object\|null	Agent identity if invoked via an agent: `id` and `name`.
`data[].api_key`	object\|null	API key reference if invoked via API key: `id`.
`data[].models.requested`	string\|null	Model name the session requested.
`data[].models.actual`	array	Model(s) that handled the invocation.
`data[].models.providers`	array	Provider(s) for the actual model(s).
`data[].workflow_job_id`	string\|null	Workflow job run ID (`source=workflow` only).
`data[].workflow_step_id`	string\|null	Workflow step ID that produced this invocation (`source=workflow` only).
`data[].resource_deleted_at`	string\|null	Timestamp when the underlying resource was soft-deleted, if applicable.
`data[].resource_expires_at`	string\|null	Timestamp when soft-deleted resource data will be permanently purged (chat only).
`data[].files`	array\|null	File references attached to this invocation. Populated only when `include_content=true` on `GET /v1/compliance/invocations/{invocation_id}`.
`data[].content`	array\|null	Full message or step content. Populated only when `include_content=true` on `GET /v1/compliance/invocations/{invocation_id}`.
`pagination.has_more`	boolean	`true` if additional results exist beyond this page.
`pagination.next_cursor`	string\|null	Pass as `cursor` on the next request to retrieve the next page.

Get Invocation

Return metadata for a single invocation by its UUID. Optionally include full message history or workflow step content.

Endpoint

GET /v1/compliance/invocations/{invocation_id}

Path Parameters

invocation_id (required): Invocation UUID (e.g. "b2c3d4e5-0000-0000-0000-000000000001").

Query Parameters

Parameter	Type	Required	Description
`include_content`	boolean	No	Set to `true` to populate `content` and `files`. Requires content access for the invocation's tenant (default: `false`).

Content access: When include_content=true:

source=chat: content contains the full DynamoDB message history; files lists all file objects scoped to the chat session.
source=workflow: content contains all workflow step run records; files lists all file objects scoped to the workflow run.

Example Query

curl 'https://ai.hatz.ai/v1/compliance/invocations/b2c3d4e5-0000-0000-0000-000000000001' \
  -H 'X-API-Key: $HATZ_API_KEY'

With content:

curl 'https://ai.hatz.ai/v1/compliance/invocations/b2c3d4e5-0000-0000-0000-000000000001?include_content=true' \
  -H 'X-API-Key: $HATZ_API_KEY'

Response

{
  "invocation_id": "b2c3d4e5-0000-0000-0000-000000000001",
  "session_id": "c3d4e5f6-0000-0000-0000-000000000001",
  "session_name": "Q2 budget analysis",
  "timestamp": "2026-05-15T14:22:00+00:00",
  "source": "chat",
  "tenant": {
    "id": "tenant_abc123",
    "name": "Acme Corporation"
  },
  "user": {
    "id": "user_xyz789",
    "email": "john.doe@acme.com",
    "name": "John Doe"
  },
  "agent": null,
  "api_key": null,
  "models": {
    "requested": "gpt-4o",
    "actual": ["gpt-4o"],
    "providers": ["openai"]
  },
  "features_used": null,
  "workflow_job_id": null,
  "workflow_step_id": null,
  "resource_deleted_at": null,
  "resource_expires_at": null,
  "files": null,
  "content": null
}

Error Responses

400 — invocation_id is not a valid UUID.
404 — Invocation not found or caller does not have access.

Compliance - Audit Events

Compliance - Settings