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. hasLineagecalculation 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 returnedqualified_name(creator(connection_qualified_name=...)). - Always reference assets by
qualified_name, notname: 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)
- Read-only (8):
- 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: GA/preview/roadmap status for every surface named here.
- API, SDK & automation best practices: 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/