Skip to content
GitmoapAPIBeta
Organizeaudit
GET/groups/{group_id}/audit-log

List an organization's audit log

list_group_audit_log
  • audit:read
    A token needs the audit:read scope: Read the audit log (org owners / platform admins)Granted by read_api, write_api.Every operation this scope unlocks
  • Single-resource

    x-gitmoap-isolation: {"kind":"single_or_self_scoped"}

  • Paginated
    Pass the cursor a page returns to get the next one.

Call it on the organization's top-level group; only its owners may read it. Records come newest first and can be narrowed by actor, target resource, category (mutation, auth_event or sensitive_read) and a time window. Filters apply to each page, so a page can hold fewer than limit records while more remain: keep reading while a cursor is returned.

Parameters

Path
  • group_idGroupId (string · uuid)The organization's top-level group
Query
  • actorstringoptionalFilter to one actor id
  • resourcestringoptionalFilter to one target resource id
  • categorystringoptionalFilter to one category (mutation/auth_event/sensitive_read)
  • fromstringoptionalLower time bound (RFC-3339, inclusive)
  • tostringoptionalUpper time bound (RFC-3339, exclusive)
  • limitinteger · int32optionalPage size (1-100, default 20)
  • cursorstringoptionalOpaque pagination cursor
  • scopestringoptionalIgnored here: this listing always reads the organization's own audit trail

Responses

200A page of audit recordsapplication/json
  • recordsarray of AuditRecord
    • The AuditRecord schema
    • actorAuditActor
      • The AuditActor schema
      • actor_typestringWhat kind of caller acted: user, service_account, pipeline_run, anonymous, or scim — an organization's identity provider calling with its SCIM token.
      • auth_methodAuthMethodjwtaccess_tokenanonymousHow the caller authenticated.
      • idstringThe id of the user, service account or pipeline run that acted, or anonymous.
      • avatar_urlstring or nulloptional
      • emailstringoptional
      • token_idstring or nulloptional
      • usernamestringoptional
    • audit_idAuditId (string · uuid)
    • categoryAuditCategorymutationauth_eventsensitive_readWhat kind of operation the record captures.
    • hashstringSHA256(canonical_json(record without hash) ‖ prev_hash), hex.
    • http_methodstring
    • monthstringThe month the record belongs to, YYYY-MM. Each month's records form one segment of the chain.
    • occurred_atstring
    • operation_idstring
    • outcomeAuditOutcomesuccessdeniedfailureThe result of the audited operation.
    • prev_hashstringHash of the previous record in the chain (genesis = 64 zeros; first of a month links to the prior month's tip).
    • recorded_atstringWhen the record was written to the log, RFC 3339 with microseconds.
    • request_idstring
    • routestring
    • scopestringWhich audit chain the record belongs to — an organisation, a user, or the platform.
    • seqinteger · int640–∞Monotonic position within (scope, month).
    • status_codeinteger · int320–∞
    • accessAccessAuditDetail or nulloptionalFor an operation that changed who can do what: each grant it made, changed or revoked, with the role before and after. Absent everywhere else — and absent fields do not enter the hash, so every record written before this field existed verifies unchanged.
    • mcpMcpAuditDetail or nulloptionalFor a request an AI agent made through the MCP server: the tool and the client. Absent everywhere else, and so outside the hash of every record that does not carry it.
      • The McpAuditDetail schema
      • toolstringThe tool whose execution made the request.
      • clientstring or nulloptionalThe client application the tool call came from, as that application named itself.
      • oauth_client_idstring or nulloptionalThe app the access token was issued to, when an app connected through sign-in — its own registered identifier, which, unlike the self-reported client name, the person consented to.
    • resource_bindingstring or nulloptional
    • source_ipstring or nulloptional
    • target_idstring or nulloptional
    • target_typestring or nulloptional
    • user_agentstring or nulloptional
  • next_cursorstring or nulloptional
200 exampleSynthesized example
{
"records": [
{
"actor": {
"actor_type": "actor-type-e435",
"auth_method": "jwt",
"id": "id-9362"
},
"audit_id": "04270861-05d8-428f-b05f-dbad604a9727",
"category": "mutation",
"hash": "hash-76c2",
"http_method": "http-method-9afb",
"month": "month-b0d7",
"occurred_at": "2026-10-15T16:57:34Z",
"operation_id": "8da40a75-0c61-4bc0-93cd-dc26c7a14280",
"outcome": "success",
"prev_hash": "prev-hash-212c",
"recorded_at": "2026-10-13T14:36:41Z",
"request_id": "e71ade38-c72b-456e-84e1-24a708946e90",
"route": "route-a6bb",
"scope": "scope-37ee",
"seq": 64,
"status_code": 68
},
{
"actor": {
"actor_type": "actor-type-f827",
"auth_method": "jwt",
"id": "id-58e0"
},
"audit_id": "fa0aa0c6-2166-4f6c-b06f-de066f1787a8",
"category": "mutation",
"hash": "hash-2693",
"http_method": "http-method-8565",
"month": "month-d38a",
"occurred_at": "2026-10-08T11:43:49Z",
"operation_id": "3874489e-2133-459a-b402-9b5386b3374e",
"outcome": "success",
"prev_hash": "prev-hash-47cb",
"recorded_at": "2026-10-15T20:26:04Z",
"request_id": "7d300c3e-694a-4949-86b4-0e2ea5a90b29",
"route": "route-fa5f",
"scope": "scope-ab70",
"seq": 41,
"status_code": 45
}
],
"next_cursor": "next-cursor-5f46"
}
400Bad request — a path parameter is not a well-formed value of its typeapplication/json
Error codes
  • BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
400 exampleSynthesized example
{
"error": {
"code": "code-8a12",
"message": "Draw the region map from operation density"
}
}
401Unauthenticated — no credential, or an invalid oneapplication/json
Error codes
  • UNAUTHORIZEDNo credential was sent, or the one sent is invalid, expired or revoked
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
401 exampleSynthesized example
{
"error": {
"code": "code-58d9",
"message": "Stream pipeline status into the run header"
}
}
403Not an Owner of the groupapplication/json
Error codes
  • FORBIDDENYou are signed in but may not do this here; reason names the permission or the rule that refused it
  • INSUFFICIENT_SCOPEThe access token lacks the scope this operation needs; required_scope names it
  • PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
403 exampleSynthesized example
{
"error": {
"code": "code-615e",
"message": "Stream pipeline status into the run header"
}
}
404Group not foundapplication/json
Error codes
  • NOT_FOUNDThe resource does not exist — or exists and you cannot see it: a private resource you have no access to answers exactly as an absent one does
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
404 exampleSynthesized example
{
"error": {
"code": "code-50dc",
"message": "Pin a page's payload to the build that rendered it"
}
}
501The audit log is not configured on this deploymentapplication/json
Error codes
  • NOT_IMPLEMENTEDThis deployment has not configured the feature the operation needs; the message names it
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
501 exampleSynthesized example
{
"error": {
"code": "code-f37d",
"message": "Label every synthesized example"
}
}

CLI

gitmoap audit list-group-audit-log

  • --group-ididThe organization's top-level group (id or group path)
  • --actorstringoptionalFilter to one actor id
  • --categorystringoptionalFilter to one category (mutation/auth_event/sensitive_read)
  • --cursorstringoptionalOpaque pagination cursor
  • --fromstringoptionalLower time bound (RFC-3339, inclusive)
  • --limitnumberoptionalPage size (1-100, default 20)
  • --resourcestringoptionalFilter to one target resource id
  • --scopestringoptionalIgnored here: this listing always reads the organization's own audit trail
  • --tostringoptionalUpper time bound (RFC-3339, exclusive)

Used in these guides