Retrieve audit events

A read-only API returning organization audit events in ascending time order.

GET https://api.spectra-app.net/api/v1/audit-events

Bearer authentication is required. Methods other than GET return 405 Method Not Allowed and Allow: GET.

Query parameters

All parameters are optional. Unknown and duplicate parameters are rejected. Timestamps must include seconds and a timezone; fractional seconds are accepted up to millisecond precision, for example 2026-09-13T00:00:00Z.

Name	Type	Description
`since`	string	Inclusive start timestamp with a timezone. UTC with Z is recommended.
`until`	string	Inclusive end timestamp. Keep it fixed throughout pagination; it cannot precede since.
`cursor`	string	Pass the previous next_cursor unchanged using URL encoding. Cursors from another organization are rejected.
`limit`	integer	Integer 1–1000; default 100 events.
`category`	string	Exact, case-sensitive category filter.
`action`	string	Exact, case-sensitive action filter.

Responses and pagination

curl

curl --fail-with-body --silent --show-error --get \
  -H "Authorization: Bearer $SPECTRA_AUDIT_TOKEN" \
  --data-urlencode 'since=2026-09-01T00:00:00Z' \
  --data-urlencode 'until=2026-09-13T00:00:00Z' \
  --data-urlencode 'limit=1000' \
  'https://api.spectra-app.net/api/v1/audit-events'

Response (JSON)

{
  "data": [
    {
      "schema_version": "1.0",
      "event_id": "example-event",
      "time": "2026-09-13T00:00:00.000Z",
      "organization_id": "example-organization",
      "category": "domain",
      "action": "domain.added",
      "outcome": "success",
      "actor": {
        "type": "user",
        "user_id": "example-user",
        "email": "owner@example.com"
      },
      "target": {
        "type": "domain",
        "id": "example-domain"
      },
      "src_ip": "192.0.2.10",
      "user_agent": null,
      "request_id": null,
      "details": {
        "name": "example.com",
        "active_requested": false,
        "schedule": "WEEKLY",
        "changed": []
      }
    }
  ],
  "next_cursor": null
}

NDJSON — Accept: application/x-ndjson

{"schema_version":"1.0","event_id":"example-event","time":"2026-09-13T00:00:00.000Z","organization_id":"example-organization","category":"domain","action":"domain.added","outcome":"success","actor":{"type":"user","user_id":"example-user","email":"owner@example.com"},"target":{"type":"domain","id":"example-domain"},"src_ip":"192.0.2.10","user_agent":null,"request_id":null,"details":{"name":"example.com","active_requested":false,"schedule":"WEEKLY","changed":[]}}

JSON returns a data array and next_cursor, which is null on the final page. Events are sorted by time, then event_id for ties. Treat the cursor as opaque and pass it with the same since / until / category / action / limit values.

With Accept: application/x-ndjson, each line has the same schema as a data event. An empty result has an empty body. X-Next-Cursor and Link: …; rel="next" are present only when another page exists. Responses use Cache-Control: no-store.

Event fields

Field	Meaning
`schema_version`	String; currently 1.0.
`event_id`	Opaque unique identifier used for deduplication.
`time`	Event timestamp in UTC.
`organization_id`	Organization identifier.
`category / action / outcome`	Classification, operation name and result. See the event catalog.
`actor`	Object: type is user / api_token / system. user_id and email are null when unknown. email reflects the address at event time.
`target`	Object with type and id, either of which may be null. The entire target is null when absent.
`src_ip / user_agent / request_id`	Source IP, User-Agent and request identifier. Null when unknown or without HTTP request context.
`details`	Event-specific object or null. See the event catalog for keys.

Audit events are retained for 366 days. Events older than 366 days are automatically deleted every hour and can no longer be retrieved through the API. Deleting an organization deletes its audit logs. For long-term storage, retrieve events before 366 days have passed and keep them in the receiving system.

Collection and overlap · Event catalog