Skip to main content

API audit usage

Atlan exposes four customer-accessible surfaces for auditing API and workflow usage in your tenant. Each surface covers a distinct slice of activity—asset write/mutation events, authentication events, workflow execution history, and tenant-level log export. Use this page to choose the right surface for your monitoring need.

Audit surfaces at glance​

SurfaceCoversAccess
Asset audit searchAsset write and mutation activityPOST /api/meta/entity/auditSearch
Authentication event streamingSign-in, sign-out, and admin eventsOTLP delivery to your cloud bucket
Workflow run historyConnector and utility workflow executionsWorkflow center in Atlan
Tenant log exportApplication, audit, workflow, and load balancer logsConfigurable bucket replication

The auditSearch API returns a record of write and mutation activity on assets in your tenant—who changed what, when, and from which client. It's backed by an Elasticsearch audit index and supports the same search DSL Atlan uses for other queries.

Common uses:

  • Identify the top API tokens or users producing write traffic over a window
  • Build a daily volume histogram of mutations, broken down by action
  • Trace recent activity for a specific asset or connection

Endpoint​

POST /api/meta/entity/auditSearch

The request body accepts a standard Elasticsearch query in a dsl envelope. Set size: 0 and add aggs to return aggregations only (no individual hits).

Authentication and scope​

Include a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Audit search results are filtered by your persona, purpose, and connection-admin policies. Records you don't have read permission on may be omitted or returned without their detail object.

Starter request: Top callers and daily volume​

The following request returns the top 20 users and top actions over the last 30 days, plus a daily mutation count.

Top callers and daily volume over the last 30 days
curl -X POST https://YOUR_TENANT.atlan.com/api/meta/entity/auditSearch \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dsl": {
      "size": 0,
      "query": {
        "bool": {
          "filter": [
            { "range": { "created": { "gte": "now-30d" } } }
          ]
        }
      },
      "aggs": {
        "by_user":   { "terms": { "field": "user",   "size": 20 } },
        "by_action": { "terms": { "field": "action", "size": 20 } },
        "by_day":    { "date_histogram": { "field": "created", "calendar_interval": "1d" } }
      },
      "track_total_hits": true
    }
  }'
Confirm aggregation field names for your tenant

The aggregation field names user and action reflect the names typically referenced in support workflows, but the canonical audit-record schema uses created, entityId, entityQualifiedName, and typeName for filtering (see the SDK reference). Run an unaggregated query with size: 1 first to confirm the exact field names returned by your tenant before scripting with them.

Filter by asset​

To return raw audit entries for a specific asset, filter by entityQualifiedName and typeName:

Last 10 audit entries for a specific asset
curl -X POST https://YOUR_TENANT.atlan.com/api/meta/entity/auditSearch \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dsl": {
      "from": 0,
      "size": 10,
      "query": {
        "bool": {
          "must": [
            { "term": { "entityQualifiedName": { "value": "default/snowflake/1234567890/DB/SCHEMA/TABLE" } } },
            { "term": { "typeName":            { "value": "Table" } } }
          ]
        }
      },
      "sort": [ { "created": { "order": "desc" } } ],
      "track_total_hits": true
    }
  }'

SDK alternative​

The same endpoint is wrapped by the Atlan SDKs. See Review asset changes for Java, Python, and Kotlin examples that build the request, paginate large result sets, and decode audit detail objects.

Authentication event streaming​

Atlan exports identity and access management (IAM) service event logs—including sign-in, sign-out, and admin events—in OpenTelemetry Protocol (OTLP) format. Logs are continuously delivered to an object storage bucket your organization owns, so you can route them into your security information and event management (SIEM) system.

Atlan supports delivery to all three major clouds:

For the JSON schema, delivery timing per cloud, and SIEM integration details, see Cloud logging and monitoring.

Workflow run history​

Every connector workflow run in your tenant has an execution record—start time, finish time, stages, status, and per-stage logs. Workflow run history is available through the in-product Workflow center, not through a customer-facing API today.

To review runs:

  1. From the left navigation in Atlan, click Workflows.
  2. Select a workflow tile.
  3. Open the Runs tab to view past executions, status, and timing. Select a specific run to view stage-level timeline and logs.

For a complete walkthrough of the interface, see Workflow center.

Workflow audit logs vs. workflow run history

The View workflow audit logs page covers configuration changes to a workflow connection (who edited which setting and when), not the execution history of a workflow run. Use the Runs tab in Workflow center for run-level data.

Workflow logs are retained for 90 days. For longer retention or programmatic access to workflow output, see surface 4.

Tenant log export​

Tenant logs—application logs, audit logs, workflow logs, workflow artifacts, and (on AWS) load balancer access logs—are written to object storage with provider-specific retention. The full inventory and retention table is documented in Tenant logs.

Atlan can additionally replicate the IAM and audit subset of these logs to a customer-owned bucket using the same OTLP pipeline described in surface 2. Configure replication using the cloud-specific guides linked under Authentication event streaming.

For point-in-time inspection of a single workflow's artifacts (extracted JSON, transform output, generated lineage), Atlan support can retrieve them from the tenant artifact path on request.

What is not available​

Atlan doesn't currently expose a customer-facing surface for any of the following:

  • Per-endpoint read-traffic counts (for example, requests per minute for a specific GET route)
  • Per-token request volume aggregated across all read endpoints
  • Raw HTTP request and response bodies for read traffic

If you need this level of visibility, contact Atlan support so the platform team can capture the requirement.

See also​