Receipts & Sessions API

The Receipts API provides read-only access to immutable execution receipts. Every tool invocation — whether from a human user, an AI agent, or a service — produces a receipt that captures the execution context, policy decision, and result status. Use receipts for audit trails, compliance reporting, and debugging failed executions.

Receipts Endpoints

Method	Path	Description
GET	/v1/receipts	Query receipts
GET	/v1/receipts/{receipt_id}	Get receipt by ID

Query Receipts

GET /v1/receipts

Returns a paginated list of execution receipts matching the specified filters. All filters are optional — omitting all filters returns the most recent receipts for the organization.

Query Parameters

Parameter	Type	Description
receipt_id	string	Filter by specific receipt UUID
principal	string	Filter by executor identity (e.g., user:jane@example.com)
tool_id	integer	Filter by tool
from	datetime	Start of date range (ISO 8601)
to	datetime	End of date range (ISO 8601)
result_status	string	ok or error
policy_decision	string	allow, deny, allow_with_redactions, or allow_with_limits
limit	integer	Max results (default 50, max 200)
offset	integer	Pagination offset

Request:

curl -X GET "https://api-genai.nexla.io/v1/receipts?tool_id=42&result_status=error&from=2025-01-01T00:00:00Z&limit=10" \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Response (200):

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "org_id": 1,
      "principal": "user:jane@example.com",
      "tool_id": 42,
      "tool_key": "read_customer_orders",
      "version": "1.0.0",
      "result_status": "error",
      "actor_type": "agent",
      "auth_type": "api_key",
      "policy_decision": "allow",
      "trace_id": "abc-123-def",
      "created_at": "2025-01-15T14:30:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Get Receipt Details

GET /v1/receipts/{receipt_id}

Returns the full receipt for a single execution, including the complete execution result. Use this when you need to inspect the input arguments hash, row counts, or truncation status that are not included in the list response.

Request:

curl -X GET "https://api-genai.nexla.io/v1/receipts/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Response (200):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "org_id": 1,
  "principal": "user:jane@example.com",
  "tool_id": 42,
  "tool_key": "read_customer_orders",
  "version": "1.0.0",
  "args_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "result_status": "error",
  "actor_type": "agent",
  "auth_type": "api_key",
  "policy_decision": "allow",
  "trace_id": "abc-123-def",
  "row_count": 0,
  "truncated": false,
  "created_at": "2025-01-15T14:30:00Z"
}

Receipt Schema

Full field reference for receipt objects:

Field	Type	Description
id	UUID	Unique receipt identifier
org_id	integer	Organization that owns the tool
principal	string	Identity of the executor (e.g., user:jane@example.com, service:etl-pipeline)
tool_id	integer	ID of the executed tool
tool_key	string	Stable key name of the tool
version	string	Tool version at time of execution
args_hash	string	SHA-256 hash of the input arguments
result_status	string	ok or error
actor_type	string	human, agent, or service
auth_type	string	api_key, oauth, oidc_jwt, or mtls
policy_decision	string	allow, deny, allow_with_redactions, or allow_with_limits
trace_id	string	Distributed trace identifier for correlating across services
row_count	integer	Number of rows returned (for data tools)
truncated	boolean	Whether the result was truncated due to size limits
created_at	datetime	Timestamp of execution (ISO 8601)