How to Export Data from Ada: API Limits, Methods & Portability

How to Export Data from Ada: API Limits, Methods & Portability

Ada gives you one primary path for getting data out: the Data Export API, a REST endpoint that returns conversation and message records as JSON. There is no bulk "download everything" button in the dashboard and no native CSV export for raw conversation data. If you need your data out of Ada — for migration, compliance, archival, or BI — you will be writing API calls or hiring someone who does.

Three hard constraints shape every extraction strategy: data is only accessible for the past 12 months, each query can span a maximum of 60 days, and rate limits cap at 10 requests per second per endpoint. Understanding these limits before you start will save you from building a pipeline that hits walls halfway through.

Document scope and dating: The API constraints in this guide reflect Ada's developer reference documentation for the generative AI platform as of mid-2026. Ada has made breaking changes to these APIs in the past (notably the CSAT v1→v2 migration and the May 2026 addition of tool_call message types). Verify current limits against Ada's official developer documentation before building production pipelines.

This guide covers every extraction method available in Ada, the exact API limits you will hit, what data you can and cannot get out, and how to plan around the portability gaps.

What Data Can You Export from Ada?

The main mistake teams make is assuming Ada has one export surface. It does not. Different object types live behind different APIs and export formats.

The Data Export API: Conversations and Messages

The Data Export API is the primary extraction tool. It exposes two endpoints:

• GET /api/v2/export/conversations — Returns conversation-level metadata: chatter ID, timestamps, CSAT score and rating, escalation status, variables, metavariables, topic classifications, and fields introduced in v2 including used_articles, used_playbooks, used_coaching, last_agent_id, and last_agent_name.
• GET /api/v2/export/messages — Returns individual messages within conversations: message body, sender type (chatter, bot, agent), timestamps, and (as of May 2026) tool_call message types for Actions and Handoffs.

Conversations and messages are separate objects. Conversation records do not include message bodies. You must query both endpoints independently, then join on conversation_id to reconstruct full transcripts. This is the single most common architectural mistake in Ada extraction pipelines.

Authentication

Generate an API key from the Ada dashboard: Settings > Integrations > APIs. Keys use Bearer token authentication and work across all APIs your organization has access to. Ada only displays the key once at creation — store it in your environment variables immediately.

API key scoping: Ada API keys are not granularly scoped by default — a key grants access to all endpoints your subscription tier includes, not read-only or export-specific access. If your security policy requires least-privilege key management, verify with Ada support whether scoped keys are available on your plan. There is no OAuth flow for the Data Export API; it is API-key-only.

API Rate Limits and Constraints

This is where most teams trip up. The Data Export API has layered limits:

The 12-month retention limit is the single biggest portability risk. If you need conversation history older than 12 months for compliance, migration, or analytics, it is gone from Ada's export pipeline. The only mitigation is to set up a continuous sync that pulls data into your own warehouse before it ages out.

If your Ada admin has configured a data retention policy shorter than 12 months, your export window shrinks accordingly. Always verify your retention settings before planning an extraction.

On 429 error handling: Ada's Data Export API returns HTTP 429 Too Many Requests when you exceed 10 req/s. The response body is a standard JSON error object; Ada does not reliably return a Retry-After header. Implement exponential backoff starting at 1 second, doubling on each retry, capped at 30 seconds. Track retry counts per chunk and alert if a chunk requires more than 5 retries — this typically indicates a platform-side issue, not a rate limit problem.

Step-by-Step: Exporting via the Data Export API

Step 1: Generate an API Key

On the Ada dashboard, go to Settings > Integrations > APIs. Click New API key, name it, and save the key immediately. Ada will not show it again.

Step 2: Build Your First Query

Queries filter by date using created_since or updated_since (mutually exclusive — you cannot combine them in a single request). Timestamps must be ISO 8601 UTC format ending with Z. All Ada timestamps are stored and returned in UTC regardless of your account's regional settings.

curl -X GET \
  'https://YOUR-HANDLE.ada.support/api/v2/export/conversations?created_since=2026-06-01T00:00:00Z&page_size=5000' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Timezone note: Ada stores all timestamps in UTC. If your reporting layer applies timezone offsets (e.g., US/Eastern = UTC-5), recalculate your created_since and created_to boundaries in UTC before querying, or you will miss conversations that fall in the offset gap at day boundaries.

For ongoing warehouse syncs, updated_since is often the safer cursor because a conversation can change after its initial creation (e.g., a CSAT rating submitted hours later). However, updated_since can cause the same conversation to appear in multiple sync windows — design your downstream storage to upsert on conversation_id, not append.

Step 3: Paginate Through Results

The response includes a meta.next_page_uri field. Follow it until it returns null. Do not construct pagination URLs manually — use the exact URI Ada returns. Self-constructed cursor URLs are the most common source of missed or duplicated records.

import requests
import time
 
base_url = "https://YOUR-HANDLE.ada.support"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
 
url = f"{base_url}/api/v2/export/conversations?created_since=2026-06-01T00:00:00Z&page_size=5000"
 
all_conversations = []
while url:
    resp = requests.get(url, headers=headers, timeout=60)
    if resp.status_code == 429:
        time.sleep(2)  # Simple backoff; implement exponential in production
        continue
    resp.raise_for_status()
    data = resp.json()
    all_conversations.extend(data["data"])
    url = data["meta"].get("next_page_uri")
    time.sleep(0.15)  # Stay within 10 req/s rate limit
 
print(f"Exported {len(all_conversations)} conversations")

Idempotency and checkpointing: If a pagination chain fails mid-run, you cannot resume from where you stopped without re-fetching the entire chunk from the start — Ada's pagination cursors are not persistent across sessions. To avoid duplicating already-written records, write each page to a staging table keyed on conversation_id and upsert into your production table after the full chunk completes. If the chunk fails, truncate staging and restart the chunk.

Step 4: Export Messages Separately

Conversation records do not contain message bodies. Query the messages endpoint with the same date range, then join on conversation_id to reconstruct readable transcripts.

curl -X GET \
  'https://YOUR-HANDLE.ada.support/api/v2/export/messages?created_since=2026-06-01T00:00:00Z&page_size=5000' \
  -H 'Authorization: Bearer YOUR_API_KEY'

The messages endpoint requires created_since and optionally accepts created_to and conversation_id. If created_to is omitted, it defaults to a 7-day window from created_since. Always specify both bounds explicitly to avoid this default truncation.

Pagination field note: The Data Export API returns meta.next_page_uri. Other Ada APIs (End Users, Audit Log) return meta.next_page_url. These are different field names. If you build a generic Ada API client, check both fields or write endpoint-specific pagination logic.

Step 5: Handle the 60-Day Query Window

To export a full 12 months, break your date range into 60-day chunks:

from datetime import datetime, timedelta
import json
import os
 
def export_chunk(since: str, to: str, endpoint: str, headers: dict, base_url: str) -> list:
    """Fetch all pages for a single 60-day chunk. Raises on unrecoverable error."""
    url = f"{base_url}/api/v2/export/{endpoint}?created_since={since}&created_to={to}&page_size=5000"
    records = []
    retry_count = 0
    
    while url:
        resp = requests.get(url, headers=headers, timeout=60)
        if resp.status_code == 429:
            wait = min(2 ** retry_count, 30)
            time.sleep(wait)
            retry_count += 1
            if retry_count > 5:
                raise Exception(f"Rate limit retries exceeded for chunk {since}→{to}")
            continue
        resp.raise_for_status()
        retry_count = 0
        data = resp.json()
        records.extend(data["data"])
        url = data["meta"].get("next_page_uri")
        time.sleep(0.15)
    
    return records
 
# Chunk a full year into 60-day windows
start = datetime(2025, 8, 12)
end = datetime(2026, 8, 12)
chunk_days = 60
checkpoint_file = "export_checkpoint.json"
 
# Load checkpoint if resuming
checkpoint = {}
if os.path.exists(checkpoint_file):
    with open(checkpoint_file) as f:
        checkpoint = json.load(f)
 
current = start
while current < end:
    chunk_end = min(current + timedelta(days=chunk_days), end)
    since = current.strftime("%Y-%m-%dT00:00:00Z")
    to = chunk_end.strftime("%Y-%m-%dT00:00:00Z")
    chunk_key = f"{since}_{to}"
    
    if chunk_key in checkpoint.get("completed_chunks", []):
        print(f"Skipping completed chunk: {since} to {to}")
        current = chunk_end
        continue
    
    print(f"Fetching {since} to {to}")
    records = export_chunk(since, to, "conversations", headers, base_url)
    
    # Write chunk records to staging, then mark checkpoint
    # ... your storage write here ...
    checkpoint.setdefault("completed_chunks", []).append(chunk_key)
    with open(checkpoint_file, "w") as f:
        json.dump(checkpoint, f)
    
    current = chunk_end

That is 7 chunks for a full year — manageable, but each chunk requires its own complete pagination loop.

Multi-handle accounts: If your organization has multiple Ada handles (common in enterprise deployments where different brands, regions, or products run separate Ada instances), you must run this extraction loop independently per handle. There is no cross-handle export endpoint. Maintain a list of handles in your configuration and iterate over them in your extraction script.

Exporting End Users, Knowledge, and Configuration

End Users API

Use GET /api/v2/end-users/ for a paginated export of user profiles. The endpoint supports a limit up to 100 records per request and cursor-based pagination (returning meta.next_page_url, not next_page_uri — see the field naming inconsistency noted earlier), or external_id lookup for custom-channel integrations. There is no dedicated bulk export endpoint — to export all user data, collect user IDs from your conversation exports and fetch profiles individually.

The per-day rate limit is 60,000 requests. That is enough for most extraction jobs, but plan your batching if you have hundreds of thousands of profiles.

Ada also supports webhook events on the End Users API for tracking profile changes in real time. The webhook payload structure mirrors the REST response object: id, external_id, email, phone, variables, metavariables, and created_at/updated_at timestamps. If you need a live sync rather than a batch export, configure the webhook endpoint and process events asynchronously (see the Webhooks section below).

One critical portability caveat: sensitive_metadata is not exportable. It is encrypted at rest, excluded from LLM context, deleted after 24 hours, and never returned in API responses. If that data matters downstream, export it from the upstream source system, not from Ada.

Knowledge API

Knowledge export is cleaner than conversation export. The Knowledge API exposes sources, articles, and tags via GET endpoints. GET /v2/knowledge/articles/ returns article content, source, tags, language, timestamps, enabled state, metadata, and availability rules.

Article endpoints are generously rated at 60,000 requests/day, 1,000/minute, and 200/second. Ada documents a default ceiling of 50,000 articles, a 100KB max article size, and a 10MB max request size. The list endpoint supports filters by article ID, enabled state, language, source, and tags, making selective exports straightforward.

Native Integrations as an Alternative Export Path

Before writing custom extraction scripts, check whether Ada's native integrations already provide the data path you need:

• Salesforce and Zendesk connectors: Ada offers native connectors for both platforms. If you are migrating to either, conversation data may flow through the connector directly rather than requiring custom API extraction. Check your Ada integration settings before building a pipeline.
• Reporting integrations: Ada can push summary analytics to BI tools via native connectors. This covers aggregate metrics but not raw conversation records.
• Custom channels: If your Ada deployment uses a custom channel, conversation events may already be flowing to your infrastructure via the channel API, bypassing the need for export API calls entirely.

These integrations are not a substitute for raw conversation export in most migration scenarios, but they eliminate the extraction layer for certain use cases.

Configuration Objects

Exporting Ada's configuration is the hardest part. Coverage is fragmented across multiple APIs:

• Persona: GET /v2/persona returns the current persona configuration, but agent identity settings (name, avatar) are excluded.
• Variables: The Variables API is read-only and returns dashboard variables as id/name summaries. Reserved and internal variables are not returned.
• Custom Instructions: The Custom Instructions API returns active and inactive instructions with cursor pagination and availability_rules. Titles are capped at 150 characters, instruction text at 300 characters per instruction.
• Playbooks and Actions: Not available via standard REST endpoints for export. Ada's MCP Server tools (get_ada_configuration, list_entities) provide stronger read access to playbook summaries, actions, and related config.
• Audit Log: The Audit Log API returns event-level change records, not a state snapshot. Query windows are capped at 30 days. The pull API is the durable record — the matching webhook is best-effort only and should not be used as the primary audit mechanism.

Treat configuration export as an inventory exercise, not a single API call. Budget time to manually document playbook logic and coaching rules — these cannot be programmatically extracted in a format that is importable to another platform.

Other Export Methods

Dashboard CSV and Legacy Exports

The Ada dashboard offers a CSV export for the Topics performance table only. This exports the current filtered view — topic-level analytics, not raw conversation or message data.

For legacy scripted bots, Ada supports exporting Answer content and training phrases to CSV or XLSX. This is useful for capturing training data before migrating to a new AI engine. Reports can also be exported as PDF or printed from the dashboard.

These are reference artifacts, not lossless exports. They are no substitute for raw API extraction if you need exact data reconstruction.

Webhooks for Real-Time Sync

If you are preparing for a cutover and need to keep a target system in sync with Ada, polling the REST API is inefficient. Ada supports webhook events for certain object types. The End Users API includes webhook events for tracking profile changes, and conversation-level events can push payloads to your endpoint when sessions complete.

Webhook payload structure (End User update example):

{
  "event": "end_user.updated",
  "timestamp": "2026-07-15T14:23:01Z",
  "data": {
    "id": "eu_abc123",
    "external_id": "user_456",
    "email": "user@example.com",
    "variables": { "plan_type": "enterprise", "account_id": "acct_789" },
    "metavariables": { "last_seen_page": "/pricing" },
    "created_at": "2025-11-01T09:00:00Z",
    "updated_at": "2026-07-15T14:23:01Z"
  }
}

The Audit Log webhook delivers the same event schema as the pull API but on a best-effort basis — it can miss events under load. Never use the Audit Log webhook as your sole compliance mechanism; always reconcile against the pull API.

GDPR and Data Subject Requests

To fulfill a data subject access request, query the Data Export API filtering by the user's chatter_id or end_user_id. For deletion requests, use the Bulk End-User Deletion API, which erases all personal data associated with one or more end users across Ada's systems. Note that deletion is irreversible and applies to conversation data as well as user profile data — export before deleting if you need records for compliance archival.

Portability Gaps and Edge Cases

No Re-Import Path for Conversations

Ada's Conversations API creates new, live conversations only. There is no POST endpoint that accepts a historical conversation object with past timestamps. You cannot round-trip conversation data. Once exported, it can go to a warehouse, a target platform, or an archive — but not back into a different Ada instance in its original form.

This is a significant limitation for Ada-to-Ada migrations.

Expiring Attachment URLs

When a user uploads a file or image during an Ada conversation, the API payload contains a URL pointing to the hosted file — not the binary data itself. These URLs are presigned and expire. If you export the JSON and try to access the attachments days later, the links will be broken.

Your extraction pipeline must detect attachment URLs in the message array, download the files immediately during the extraction process, and upload them to your own storage or directly into the target system's attachment API. Ada does not publish the exact TTL for presigned attachment URLs — treat any URL more than 24 hours old as potentially expired.

PII Redaction Is One-Way

Ada features built-in PII redaction. If a user types a credit card number or Social Security Number, Ada masks it before storing. When you export via the API, redacted data stays redacted — it appears as [REDACTED] or a similar token. This is a one-way transformation. You cannot recover the original data during export.

CSAT Data: v2 Only

The Conversations endpoint returns CSAT v2 data only. If your Ada instance has older CSAT v1 data from before the migration to CSAT 2.0, that data will not appear in API responses. If continuity of CSAT metrics is a compliance or analytics requirement, request a historical CSAT data export from Ada support before the v1 records age out of the 12-month window entirely.

Metavariable and Variable Truncation

In Data Export API versions 1.2 and earlier, the variables field has a maximum length of 1,000 characters. Long-form data stored in variables may be silently truncated — the field is cut without warning or error flag in the response. Use v2 endpoints wherever available, and validate variable field lengths in your extraction output against the source data if possible.

Pagination Field Naming Is Not Uniform

Data Export returns meta.next_page_uri. End Users and Audit Log return meta.next_page_url. Always consume the exact field Ada returns instead of generating cursor URLs yourself — hand-built cursor logic is a common source of missed or duplicated records across endpoints.

Timezone Normalization

All Ada timestamps (created_at, updated_at, conversation started_at) are returned in UTC. If your data warehouse, BI tool, or target system stores timestamps in local time, apply timezone conversion after export — not by adjusting your query window boundaries. Adjusting query boundaries by timezone offset is unreliable because conversations can start in one timezone-day and complete in another.

Structuring Ada Data for Helpdesk Migrations

If you are extracting data to move to a traditional ticketing system, you face a fundamental data model mismatch. Ada stores continuous chat conversations; helpdesks store discrete tickets with threaded replies.

Migration Transformation Decision Tree

Is your target system a helpdesk (Freshservice, Desk365, Zendesk, etc.)?
├── YES → Do conversations contain escalations to human agents?
│   ├── YES → Map escalated conversations as tickets; non-escalated as internal notes or closed tickets
│   └── NO → Map each conversation as a closed ticket with bot messages as internal notes
└── NO (data warehouse / BI tool)
    ├── Flatten to two tables: conversations + messages, joined on conversation_id
    └── Preserve JSON columns for variables/metavariables rather than normalizing prematurely

Does your target require ticket subjects?
├── YES → Generate from first chatter message (truncated to 50 chars) or primary intent label
└── NO → Skip

Do you have Ada variables that map to target custom fields?
├── YES → Build explicit field mapping before import; missing fields cause silent data loss
└── NO → Log variables to a freeform notes field as key-value pairs

The core transformation work for helpdesk migrations includes:

1. Synthesizing subject lines. Ada conversations do not have subjects. Most ticket systems require them. Generate one programmatically — typically the first ~50 characters of the chatter's first message, or the name of the primary intent triggered.
2. Mapping variables to custom fields. Ada stores custom data as key-value pairs in the variables object. These must be mapped to custom fields in the target system before import. If a corresponding custom field does not exist in the target, the data will be silently dropped — it will not error, it will simply disappear.
3. Converting message arrays to ticket threads. The array of Ada messages must become a chronological thread of ticket replies. Map the sender attribute: bot messages → internal notes or agent replies; chatter messages → customer replies.
4. Joining conversations and messages. Since Ada exports them via separate endpoints, join on conversation_id before constructing ticket objects. A conversation record with no corresponding messages in your extract indicates a failed pagination or a retention gap, not an empty conversation.
5. User identity mapping. Ada's chatter_id or end_user_id must map to the target system's requester concept. If your Ada deployment uses anonymous chatters (no external_id set), you will need to deduplicate on email or phone extracted from the conversation messages themselves.
6. Handling escalated vs. bot-only conversations. Many helpdesk imports treat escalated conversations differently (as human-resolved tickets) vs. bot-resolved conversations (as closed/deflected). Use the escalation_status and last_agent_id fields from the conversation export to drive this split.

For teams migrating to specific platforms, we have covered the destination-side details in our Ada to Desk365 migration guide and Ada to Freshservice guide. If you are flattening JSON to CSV for import, our CSV migration guide covers the trade-offs.

Timing Estimates for Full Extraction

At 10 requests/second with 5,000 records per page, rough estimates for a full conversation + message export (both endpoints combined):

These estimates assume clean pagination with no retries and single-handle accounts. Add buffer for:

• 429 rate-limit responses requiring exponential backoff
• Network timeouts (recommend 60-second request timeout)
• 60-day chunking overhead (7 chunk boundaries per year × both endpoints)
• Attachment download time if your pipeline retrieves binary files
• Multi-handle account multiplication (one full run per handle)

When to DIY vs. When to Get Help

DIY makes sense when:

• You are exporting for BI or analytics and have an engineer who can write Python pagination scripts
• Volume is under ~50,000 conversations
• You do not need to transform data for a target platform
• You have time to handle edge cases (truncated variables, CSAT version mismatches, timezone normalization, attachment URL expiration)
• Your account has a single Ada handle

Get help when:

• You are migrating to another platform and need conversation-to-ticket transformation
• You have 12+ months of data and have not been archiving — some of it may already be lost
• You need to map Ada variables and metavariables to target custom fields with complex business logic
• Your compliance team requires a verified, auditable extraction with zero data loss and reconciliation reporting
• You need configuration capture (playbooks, coaching) alongside conversation data
• You have multiple Ada handles and need a coordinated, consistent extract across all of them