> For the complete documentation index, see [llms.txt](https://knowledgebase.fabricdata.com/studio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledgebase.fabricdata.com/studio/integrations-and-apis/origin-studio-production-api/audit.md).

# Audit

Read your tenant's audit events. Start a query with `POST /auditQueries`, then poll `GET /auditQueries/{queryExecutionId}` for results.

## Start an audit query

> Starts an audit query for your tenant and answers 202 with its \`queryExecutionId\`. Poll \`GET /auditQueries/{queryExecutionId}\` until the status is \`SUCCEEDED\` or \`FAILED\`.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Audit","description":"Read your tenant's audit events. Start a query with `POST /auditQueries`, then poll `GET /auditQueries/{queryExecutionId}` for results."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"AuditQueryCreateOneRequest":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IAuditQueryCreateOneRequest","description":"An audit query to start.","type":"object","additionalProperties":false,"required":["data"],"properties":{"meta":{"$ref":"#/components/schemas/WriteRequestMeta"},"data":{"type":"object","additionalProperties":false,"required":["type","attributes"],"properties":{"type":{"type":"string","enum":["auditQueries"]},"attributes":{"type":"object","additionalProperties":false,"required":["dateFrom","dateTo"],"properties":{"dateFrom":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Start of the date range (inclusive), YYYY-MM-DD"},"dateTo":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"End of the date range (inclusive), YYYY-MM-DD"},"resourceTypes":{"type":"array","items":{"type":"string","pattern":"^KS::[A-Za-z]+$"},"description":"Resource type keys to filter by; matches any of them"},"search":{"type":"string","maxLength":200,"description":"Matches `resourceName` as a case-insensitive substring, or `rootEntityId` exactly"},"recordId":{"type":"string","maxLength":100,"description":"Scopes the query to one record's change history (exact `rootEntityId` match). Needs history access to that record, so your policy's work-type, lifecycle and security-tag scoping applies. Without `recordId`, the query covers the whole tenant (the Administration audit log) and only administrators can run it. `search` can't scope to one record: it also matches `resourceName`."}}}}}}},"WriteRequestMeta":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteRequestMeta","description":"Audit metadata for a write request. `audit.source` names the surface that sent it, such as `studio-web`, `studio-mcp`, `api` or `system`; `audit.reason` is a free-text justification.","type":"object","additionalProperties":false,"properties":{"audit":{"type":"object","additionalProperties":false,"properties":{"source":{"type":"string","maxLength":64},"reason":{"type":"string","maxLength":256}}}}},"AuditQueryCreateOneResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IAuditQueryCreateOneResponse","description":"The started audit query. Poll `GET /auditQueries/{id}` for results.","type":"object","additionalProperties":false,"required":["data","jsonapi"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"Query execution ID: pass it as the path parameter when you poll"},"type":{"type":"string","enum":["auditQueries"]},"attributes":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["RUNNING"],"description":"Always `RUNNING` for a new query"}}}}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/auditQueries":{"post":{"summary":"Start an audit query","description":"Starts an audit query for your tenant and answers 202 with its `queryExecutionId`. Poll `GET /auditQueries/{queryExecutionId}` until the status is `SUCCEEDED` or `FAILED`.","operationId":"auditQueryCreateOne","tags":["Audit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditQueryCreateOneRequest"}}}},"responses":{"202":{"description":"Query started: poll for results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditQueryCreateOneResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Poll an audit query for results

> Returns the audit query's current status:\
> \- \`QUEUED\` or \`RUNNING\`: 202 with an empty \`data\` array. Poll again.\
> \- \`FAILED\`: 202 with an empty \`data\` array and \`meta.status: FAILED\`. Start a new query.\
> \- \`SUCCEEDED\`: 200 with up to 1,000 audit events. \`meta.hasMore: true\` means the results stop at 1,000; narrow the filters to see them all.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Audit","description":"Read your tenant's audit events. Start a query with `POST /auditQueries`, then poll `GET /auditQueries/{queryExecutionId}` for results."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"AuditQueryFindOneResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IAuditQueryFindOneResponse","description":"An audit query poll result: 202 while `RUNNING` or `FAILED`; 200 with events in `data` when `SUCCEEDED`.","type":"object","additionalProperties":false,"required":["data","meta","jsonapi"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"},"description":"Audit events. Empty until the status is `SUCCEEDED`."},"meta":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["QUEUED","RUNNING","SUCCEEDED","FAILED"],"description":"Current query execution state"},"hasMore":{"type":"boolean","description":"`true` when the results exceed 1,000 events. Narrow the filters to see them all."}}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"AuditEvent":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IAuditEvent","description":"JSON:API resource object for a single audit event","type":"object","additionalProperties":false,"required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"Unique event ID"},"type":{"type":"string","enum":["auditEvents"]},"attributes":{"$ref":"#/components/schemas/AuditEventAttributes"}}},"AuditEventAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IAuditEventAttributes","description":"Attributes of a single audit event captured from a Keystone entity change","type":"object","additionalProperties":false,"required":["rootEntityId","tenantId","timestamp","actorId","actorName","actorType","action","resourceType","resourceId","resourceName"],"properties":{"rootEntityId":{"type":"string","description":"ID of the root entity this event is grouped under"},"tenantId":{"type":"string","description":"Tenant that owns this event"},"timestamp":{"type":"string","description":"ISO 8601 timestamp of when the event occurred"},"actorId":{"type":"string","description":"ID of the user or system that triggered the change"},"actorName":{"type":"string","description":"Display name of the actor"},"actorType":{"type":"string","description":"Type of actor (e.g. user, system)"},"action":{"type":"string","description":"Cedar action that was performed (e.g. updateRecord)"},"changeSource":{"type":"string","description":"Source system or surface that triggered the change"},"changeReason":{"type":"string","description":"Optional free-text reason provided by the actor"},"resourceType":{"type":"string","description":"KS:: prefixed entity type (e.g. KS::Record)"},"resourceId":{"type":"string","description":"ID of the specific resource that changed"},"resourceName":{"type":"string","description":"Display name of the resource at the time of the event"},"changesJson":{"type":"string","description":"JSON-encoded diff of the changes made"}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/auditQueries/{queryExecutionId}":{"get":{"summary":"Poll an audit query for results","description":"Returns the audit query's current status:\n- `QUEUED` or `RUNNING`: 202 with an empty `data` array. Poll again.\n- `FAILED`: 202 with an empty `data` array and `meta.status: FAILED`. Start a new query.\n- `SUCCEEDED`: 200 with up to 1,000 audit events. `meta.hasMore: true` means the results stop at 1,000; narrow the filters to see them all.","operationId":"auditQueryFindOne","tags":["Audit"],"parameters":[{"name":"queryExecutionId","in":"path","required":true,"description":"The query execution ID from `POST /auditQueries`.","schema":{"type":"string"}},{"name":"recordId","in":"query","required":false,"description":"Send the same `recordId` that started the query. A record-scoped poll needs history access to that record, as the create did, and returns only that record's events. Omit it to poll a tenant-wide Administration query; only administrators can poll those.","schema":{"type":"string","maxLength":100}}],"responses":{"200":{"description":"Query succeeded: audit events in `data`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditQueryFindOneResponse"}}}},"202":{"description":"Query still running or failed: poll again or check `meta.status`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditQueryFindOneResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
