## API limits, batching, and automation reference

URL: https://docs.atlan.com/product/capabilities/build-apps/references/api-limits-and-automation

> Rate limits, batching sizes, retry/backoff standards, client requirements, and hard constraints for Atlan's programmatic surfaces—REST API, SDKs, webhooks, governance workflows, and the MCP server.

# API limits, batching, and automation reference

The load-bearing numbers and hard constraints for building against Atlan programmatically. Mechanism-selection guidance (which surface to use when) lives in the API, SDK & automation best-practices guide—this page is the fact sheet it builds on.

## Rate limit

- **400 requests/minute**: the global limit on programmatic API calls (SDK `.save()` and custom integrations). Exceeding it returns **HTTP 429** and blocks further programmatic requests for **1 minute**. UI actions are unaffected.
- Rate limits are **global per instance, not per-domain**. There is no per-domain throttling knob. For multi-region writers to one instance, coordinate throttling with a global queue in front of the instance. Instance sizing is adjustable on request.

## Core APIs

| API | Purpose | Endpoint |
|---|---|---|
| IndexSearch | Reading assets (search / discovery / retrieval) | `POST /api/meta/search/indexsearch` |
| Bulk | Writing assets (create / update / relationships) | `POST /api/meta/entity/bulk` |

The metastore is a shared service operating at millions-to-billions of assets. It isn't guaranteed to be always fast or available—clients must be built for resilience.

## Batching reference

| Operation | Batch size |
|---|---|
| Bulk writes (`/api/meta/entity/bulk`, SDK bulk save) | **20–50 entities per request**; if a response exceeds 5 s, reduce batch size |
| IndexSearch GUID queries | up to **100 GUIDs per request** |
| Metastore callbacks (when unavoidable) | **20–100 assets per call**; queue high volume into controlled batches |

- Use bulk save, never one-by-one: `Asset.save(assets=[asset1, asset2, asset3])`.
- Limit returned attributes and paginate large IndexSearch result sets.

## Required client behavior

### Client identification headers

Send standardized headers so the platform can prioritize and throttle:

| Header | Notes |
|---|---|
| `x-atlan-agent-id` | **Critical—used for rate limiting** |
| `x-atlan-client-origin` | `numaflow` / `workflow` / `product_sdk` |
| `x-atlan-agent-package-name` | |
| `x-atlan-agent-workflow-id` | |
| `x-atlan-request-id` | Tracing—log this for every failure |
| `x-atlan-client-user-agent` | |

### Retry, backoff, and dead-letter queue

Expect 429 (rate limited), 503 (maintenance/incident), and high latency. Implement exponential backoff plus a dead-letter queue (DLQ) for exhausted retries:

| Attempt | Wait | Retry on |
|---|---|---|
| 1 | 2 s | 429, 500, 502, 503, 504 |
| 2 | 4 s | same |
| 3 | 8 s | same |
| 4 | 16 s | same |
| 5+ | 32 s (cap) | same |

On exhaustion: serialize the failed request with metadata (timestamp, error, retry count), log with the request ID, alert on DLQ accumulation, replay after maintenance.

### Client grading

Clients are graded **A (Gold) → D (Throttled)** on client identification, retry logic, callback pattern, error handling, and data-loss prevention. The grade determines throttling priority and maintenance-window treatment.

### Operational targets

Success rate 99.5% (alert < 99%) · P95 latency < 5 s (alert 10 s) · retry rate < 2% (alert 5%) · DLQ depth 0 (alert 100) · 429 rate < 0.1% (alert 1%). Correlate logs on `x-atlan-request-id`.

### Anti-patterns with platform-level consequences

- **Cascading metastore callbacks** (event → read → write → new event → read again) raise P99 latency for all tenants. Prefer event-driven processing—events already carry GUID, changed attributes, and relationship/classification/lineage changes.
- **Create-delete cycles** (for example, re-creating a catalog daily) cause tombstone accumulation, ghost vertices, and TypeDef cache churn. Use status flags / TTL cleanup, and coordinate large cleanups with Atlan.

## Write-path performance facts

- **Append/remove relationship attributes** (`appendRelationshipAttributes` / `removeRelationshipAttributes`) avoid resending all existing relationships. Measured at scale (attaching a term to 40k assets each carrying ~1,000 relationships): payloads dropped from 1,001 entities to 1; median 1.9 s, P95 3.9 s, 0% failures across 1,743 requests.
- `hasLineage` calculation is **asynchronous**: large lineage recompute is off the request path.
- Bulk ingestion phases: Validation → Authorization → Diff → **Lineage calculation (high cost)** → Propagation (high cost) → Persist → Notifications → Audits. Avoid unnecessary attribute updates (diff cost); lineage and tag propagation are the expensive phases.

## SDK and asset-model hard constraints

- API keys are generated at **Admin → API Tokens → Generate Token**. Atlan provides **no token-usage report**; the token's creation date in the API-tokens admin panel is the proxy for identifying which integration uses it.
- **Asset hierarchy is strict:** `Connection → Database → Schema → Table → Column`. Children are created beneath the parent by chaining the parent's returned `qualified_name` (`creator(connection_qualified_name=...)`).
- **Always reference assets by `qualified_name`, not `name`**: names can be duplicated across the workspace.
- **TypeDefs:** a source with no native connector can be mapped to existing TypeDefs (database/schema/table/column) so it joins the metadata graph; if no suitable TypeDef exists, create a custom entity. Supported TypeDef categories: API, Relational DB, Non-Relational DB, Custom, Application, Data Model assets. Reference: developer.atlan.com/models/
- **API overage handling is a commercial term set by your contract, not a product limit**: confirm your specific entitlement terms with your Atlan account team.

## Webhooks

- Atlan sends an HTTP POST payload to a preconfigured **HTTPS** endpoint on events (metadata change, user activity, catalog update). Payload carries asset details, timestamps, and context.
- **Hard limit: there is no webhook for governance-workflow completion**: poll the workflow API instead.
- AWS Lambda pattern: developer.atlan.com/patterns/events/aws-lambda-webhooks/

## Governance workflows—programmatic support matrix

| Ask | Status |
|---|---|
| SDK/API to **create or manage** governance workflows | **Not supported.** No official SDK or public API. Create the workflow in the UI, then hardcode its (constant) workflow GUID for programmatic use. |
| **Programmatically invoke** a workflow and retrieve status | Supported via REST. A single `POST https://{tenantUrl}/api/service/approval-workflow-requests` submits **and** triggers the request; capture `runs[].guid` and `runs[].status` from the response; `GET` on the run GUID polls status. **No webhook—polling is required.** |
| **Bulk-approve** pending requests | **No native bulk-approve endpoint.** Approve requests individually via the documented approval flow. Approvals are **final, with no undo**. |

Invocation prerequisites: valid API token; the workflow must already exist in the UI (its GUID is hardcoded); payload carries `workflow_type` (for example, `PUBLICATION_MANAGEMENT`), optional `comment`, and the entity block for the proposed change. The ~400 RPM programmatic ceiling applies to bulk operations.

## Cross-tenant portability

| Artifact | Portable across tenants? |
|---|---|
| Playbooks | **No**: connection- and DSL-query-specific per tenant |
| Live cross-tenant sync (read/write between tenants in one operation) | **Not a product capability**: custom Professional Services build |

## Custom packages

Pre-built, schedulable batch processes that run inside Atlan (create lineage, bulk import/export metadata, send notifications, migrate enrichments). Browse at solutions.atlan.com; installed into the instance by the Atlan account team.

## MCP server

- **Self-hosted MCP server: GA**: public repo `github.com/atlanhq/agent-toolkit/tree/main/modelcontextprotocol`.
- **Hosted MCP server: private preview**: opt-in per customer; supports **OAuth 2.0 and API-key** authentication. An API key doesn't enforce per-user identity; an OAuth client (client ID + secret) governs MCP calls per individual SSO identity, preserving persona/permission mappings.
- **Tool catalog: 28 tools**, gated per-tenant via feature flags (a tool missing from a session usually means the flag is off for the tenant, or the underlying feature isn't enabled):
 - Read-only (8): `semantic_search_tool`, `search_assets_tool`, `traverse_lineage_tool`, `query_assets_tool`, `resolve_metadata_tool`, `search_atlan_docs_tool`, `get_asset_tool`, `get_groups_tool`
 - Write/update (7): `update_assets_tool`, `update_dq_rules_tool`, `schedule_dq_rules_tool`, `manage_announcements_tool`, `add_attributes_to_cm_set_tool`, `update_custom_metadata_tool`, `add_atlan_tags_tool`
 - Create (7): `create_glossaries`, `create_glossary_terms`, `create_glossary_categories`, `create_domains`, `create_data_products`, `create_dq_rules_tool`, `create_custom_metadata_set_tool`
 - Destructive (6): `delete_dq_rules_tool`, `delete_custom_metadata_set_tool`, `remove_attributes_from_cm_set_tool`, `remove_custom_metadata_tool`, `remove_atlan_tag_tool`, `manage_asset_lifecycle_tool` (archive/restore/purge)
- Client coverage: Claude, Cursor, Windsurf, n8n, VS Code, and any spec-compliant MCP client.
- Behavior fact: the MCP returns **what's asked** and doesn't expand query scope on its own—breadth must be encoded in the query (or a skill/instruction file), not assumed.
- Setup options: tool scoping (read-only vs write via restriction flags); transport mode (streamable HTTP for production, local async for testing); optional agent ID for tracing.

## Related

- [Feature maturity matrix](https://docs.atlan.com/llms/platform/get-started/feature-maturity-matrix/llms.txt): GA/preview/roadmap status for every surface named here.
- [API, SDK & automation best practices](https://docs.atlan.com/llms/platform/build-apps/choose-how-to-automate/llms.txt): which mechanism to use when.
- Endpoint reference: developer.atlan.com/endpoints/ · SDK: developer.atlan.com/sdks/python/ · Snippets: developer.atlan.com/snippets/ · Patterns: developer.atlan.com/patterns/

---