audit

Embed
Preview of the card
<a href="https://gaiadesk.net/docs/ref-audit"><img src="https://gaiadesk.net/docs/_api/public/orgs/89a5df38-be2c-4963-8823-21d4bd40a2ab/spaces/57b99ea0-d45a-4986-8aa6-6b0683c9fe1d/pages/5b5171e9-9f7c-449b-876e-f78621115a68/social-card.svg?v=3e7ae33eec8b" alt="audit" width="600" height="315"></a>
GEThttps://api.gaiadesk.net/v1/auditScope audit:read

Audit events about the caller and their own desks, newest first.

Atlas audit events: desk sessions, agent-token activity reported by desks, and every API call (api.*: actor, key, desk, operation and result; never a body). A team's whole trail stays in the team console and its SIEM stream.

Parameters

deskstringquery
Only events about this desk (one of the caller's own).
actorstringquery
Only events by this actor id (an email, a token id).
actionstringquery
Only this action, or every action under it when it ends in .* (api.*).
tokenstringquery
Only events by this agent token id or API key id.
since_msintegerquery
until_msintegerquery
limitintegerquery
At most this many (default 100, at most 500).

Code samples

cURL
curl -X GET "https://api.gaiadesk.net/v1/audit" \
  -H "Authorization: Bearer $GAIADESK_API_KEY"
TypeScript
Python
Go
PHP
Ruby
Java

Responses

200 The events.
Example
{
  "events": [
    {
      "id": "string",
      "action": "string",
      "stream": "string",
      "occurred_at_ms": 0,
      "actor": {
        "type": "string",
        "id": "string"
      },
      "target": {
        "type": "string",
        "id": "string",
        "name": "string"
      },
      "metadata": {}
    }
  ]
}
Schema
eventsApiAuditEvent[]required
Show child parameters
idstringrequired
actionstringrequired
desk.session.start, agent.exec, api.wakeDesk, …
streamstringrequired
session, agent, enterprise, api.
occurred_at_msintegerrequired
actorobjectrequired
Show child parameters
typestring
idstring
targetobject
Show child parameters
typestring
idstring
namestring
metadataobjectrequired
Headers
X-Request-Idstring
This request's id (req_…), also in every error body. Quote it to support.
400 The request is malformed (usage).
Example
{
  "error": {
    "desk": "string",
    "kind": "string",
    "message": "string",
    "reason": "string",
    "request_id": "string",
    "status": 0
  },
  "e2e": {
    "v": 0,
    "events": [
      {
        "seq": 0,
        "nonce": "string",
        "ciphertext": "string"
      }
    ]
  }
}
Schema
errorError & objectrequired
The CLI's error object plus this request's id.
Show child parameters
deskstring
The desk it concerned, when there was one.
kindstringrequired
The six kinds a program branches on. Stable: a new kind would be a breaking change, so match with a wildcard arm anyway.
messagestringrequired
reasonstring
The finer cause: offline, unknown_desk, not_online, network, not_signed_in, timeout, local, …
request_idstringrequired
statusinteger
Only in a held body (GaiaDesk-Held) — the HTTP status this failure would have had, had its 200 not been sent already.
e2eobject
An end-to-end encrypted operation's events; the last opens to the desk's real error (its message here is a placeholder).
Show child parameters
vintegerrequired
eventsApiE2eFrame[]required
Show child parameters
seqintegerrequired
noncestringrequired
ciphertextstringrequired
401 No credential, or one that does not verify (refused, unauthenticated).

Same as 400 · GET /audit

403 The credential lacks the scope, or may not use this API (refused).

Same as 400 · GET /audit

404 No such desk or resource visible to the caller (unreachable, unknown_desk).

Same as 400 · GET /audit

429 Over this key's rate limit (refused, rate_limited).

Same as 400 · GET /audit

Headers
Retry-Afterinteger
Seconds to wait before trying again.
RateLimit-Limitinteger
Requests allowed per window for this key.
RateLimit-Remaininginteger
Requests left in the current window.
RateLimit-Resetinteger
Seconds until the window resets.
504 A service behind the API did not answer in time (unreachable).

Same as 400 · GET /audit

Updated