Agent self-audit feed | Saperly Docs

Returns the agent-stamped audit feed across calls, SMS, compliance events, and billing transactions for a single API key. Authenticates with a regular child API key (NOT a service key). `api_key_id=self` (default) resolves to the caller's own key. A non-self UUID must belong to the caller's user AND share the caller's environment — cross-user and cross-environment lookups return 404 (existence-leak protection). Line-scoped keys (`line_id != null`) may only read THEIR OWN activity; cross-key reads against a non-self target return 403 `agent_scope_error`. Wildcard (account-wide) keys may read any of their own keys' activity. Every successful read writes an `audit_read` compliance event (audit-of-audit). Rate-limited to 60 requests per hour per user. Inbound carrier-initiated traffic (no actor key) is EXCLUDED by design — the feed answers "what did this agent do", not "what did this line receive".

Line-scoped keys (line_id != null) may only read THEIR OWN activity; cross-key reads against a non-self target return 403 agent_scope_error. Wildcard (account-wide) keys may read any of their own keys’ activity.

Every successful read writes an audit_read compliance event (audit-of-audit). Rate-limited to 60 requests per hour per user. Inbound carrier-initiated traffic (no actor key) is EXCLUDED by design — the feed answers “what did this agent do”, not “what did this line receive”.

Authentication

AuthorizationBearer

Send as Authorization: Bearer <your-key>. Obtain keys from the portal — prefix sk_live_ for production, sk_test_ for sandbox.

Query parameters

api_key_idstringOptionalDefaults to self

self (default) or the UUID of another API key owned by the authenticated user in the same environment.

limitintegerOptional1-500Defaults to 100

Maximum number of events (1-500)

event_typesstringOptional

Comma-separated list filtering the discriminator. Allowed: call, sms, compliance_event, billing_transaction. Unknown values return 422 with the allowed set named.

Response

Audit feed

eventslist of objects

limitinteger

The effective limit applied (clamped to 1-500).

api_key_idstring

Resolved API key UUID — self is replaced with the caller’s own key id in the response so callers can correlate.

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

Send as Authorization: Bearer <your-key>. Obtain keys from the portal — prefix sk_live_ for production, sk_test_ for sandbox.

self (default) or the UUID of another API key owned by the authenticated user in the same environment.

Maximum number of events (1-500)

Comma-separated list filtering the discriminator. Allowed: call, sms, compliance_event, billing_transaction. Unknown values return 422 with the allowed set named.

The effective limit applied (clamped to 1-500).

Resolved API key UUID — self is replaced with the caller’s own key id in the response so callers can correlate.

1	const url = 'https://saperly.com/api/v1/audit?api_key_id=self';
2	const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
3
4	try {
5	const response = await fetch(url, options);
6	const data = await response.json();
7	console.log(data);
8	} catch (error) {
9	console.error(error);
10	}

1	{
2	"events": [
3	{
4	"type": "call",
5	"id": "string",
6	"createdAt": "2024-01-15T09:30:00Z",
7	"data": {}
8	}
9	],
10	"limit": 1,
11	"api_key_id": "string"
12	}

1	const url = 'https://saperly.com/api/v1/audit?api_key_id=self';
2	const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
3
4	try {
5	const response = await fetch(url, options);
6	const data = await response.json();
7	console.log(data);
8	} catch (error) {
9	console.error(error);
10	}

1	{
2	"events": [
3	{
4	"type": "call",
5	"id": "string",
6	"createdAt": "2024-01-15T09:30:00Z",
7	"data": {}
8	}
9	],
10	"limit": 1,
11	"api_key_id": "string"
12	}