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

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

Gladly does not have a one-click "export everything" button. Getting your data out requires a combination of the Export API (bulk file-based extraction), the REST API (per-entity retrieval), the Reports API (CSV metric exports), and the Events API (near-real-time stream). The right method depends on whether you need conversation transcripts, customer profiles, operational reports, or a complete data dump for migration.

This guide covers every extraction path, their technical constraints, the rate limits you will hit, portability gaps that catch teams off guard, and the schema detail needed to build a working parser.

Understanding Gladly's Data Model Before You Export

Before extracting anything, you need to understand what you are extracting. Gladly is a person-centric platform, not a ticket-centric one. The core entity is the Customer — a persistent profile with a continuous timeline of Conversations. Each Conversation contains Conversation Items: emails, chat messages, SMS messages, phone calls, voicemails, notes, topic changes, and status changes.

There are no discrete ticket numbers. An agent sees one lifelong conversation stream per customer across all channels.

This architecture affects export planning in three ways:

1. There is no "ticket export." You export Conversation Items — individual messages and events within Conversations.
2. Customer profiles are the anchor. Every conversation item references a customerId. To reconstruct a full interaction history, you start from customers.
3. Channel diversity means schema diversity. A single export file contains chat messages, emails, phone call metadata, voicemails, and notes — each with a different content schema nested under the content field. A parser that only handles email and chat will break when it hits phone call records. The eleven distinct content.type values each have different required fields — see the schema reference section below.

Merged profiles add complexity. Gladly allows agents to merge duplicate customer profiles. A GET request on a merged customer's old ID returns a 301 redirect to the new ID. Your extraction script must follow these redirects and maintain a merge-resolution table, or you will duplicate customers or lose attribution on historical conversations. If the redirect is not followed, the API returns the 301 with a Location header pointing to the canonical ID — your HTTP client must be configured to follow redirects automatically, or handle them explicitly. Webhook events also fire on customer merges, which matters for ongoing syncs.

For a deeper look at Gladly's architecture, see The Ultimate Guide to Mastering Gladly.

Method 1: The Export API (Bulk File-Based Extraction)

Best for: Full data dumps, warehouse ingestion, migration prep, compliance archives.

The Export API is Gladly's primary bulk extraction mechanism. It generates JSONL files (one JSON object per line) containing your organization's data.

How It Works

Each Gladly organization has a scheduled export job — typically running every 24 hours. You can request hourly schedules or one-time exports by contacting Gladly Support; these cannot be created programmatically via API. A completed export job produces four files:

Key Constraints

• Files expire after 14 days. If you do not download them within that window, they are gone. Contact Gladly Support to regenerate.
• Default export covers only the last 24 hours (or hourly window). This is not a full-instance dump — it captures communications delivered within the specified date range.
• One-time exports covering more than six months may incur a service fee.
• Hourly schedules run on a ~2-hour lag. For an hourly schedule with a nextStartAt of 2024-01-21T08:00:00Z, the next job will not be created until approximately 10:00:00Z.
• Historical data older than 14 days requires contacting Gladly Support to regenerate the export files.
• In rare cases, conversation items with invalid attributes can be excluded from a data export, per Gladly's documentation. Build in record count reconciliation against the Conversation Summary Report to detect these exclusions.
• No sandbox environment mirrors production for export testing. Test extraction scripts against a production tenant with a limited date range before running a full historical pull.

One documentation discrepancy worth noting: Gladly's help article on transcript export mentions a limit of 2,000 conversation items per export file, while the developer docs describe job-based JSONL exports without that same ceiling. If your project depends on single-file sizing assumptions, verify against your tenant or confirm with Gladly Support before cutover.

Data volume planning: A Gladly organization with 100,000 customers and three years of multi-channel history will typically produce a conversation_items.jsonl in the range of several gigabytes per full export. Parse these files in streaming fashion (line by line) — loading the full file into memory will exhaust available RAM at scale.

You can subscribe to the EXPORT_JOB/COMPLETED webhook event to automate downstream processing as soon as files are ready. The webhook payload for this event has the following structure:

{
  "id": "webhook-event-id",
  "timestamp": "2026-08-01T06:00:00.000Z",
  "type": "EXPORT_JOB/COMPLETED",
  "payload": {
    "jobId": "aB3cD4eF5gH6iJ7kL8mN9o",
    "organizationId": "your-org-id",
    "status": "COMPLETED",
    "startAt": "2026-07-31T00:00:00Z",
    "endAt": "2026-08-01T00:00:00Z"
  }
}

Use the jobId from this payload to retrieve the file list via the REST API.

Retrieving Export Files via API

# 1. List completed export jobs
curl -u user@org.com:$TOKEN \
  https://org.gladly.com/api/v1/export/jobs?status=COMPLETED
 
# 2. Get job details (includes file list)
curl -u user@org.com:$TOKEN \
  https://org.gladly.com/api/v1/export/jobs/{jobId}
 
# 3. Download a specific file
curl -u user@org.com:$TOKEN \
  https://org.gladly.com/api/v1/export/jobs/{jobId}/files/conversation_items.jsonl \
  -o conversation_items.jsonl

Authentication error handling: If the API token is invalid or the associated user has been deactivated, the API returns 401 Unauthorized with body {"error": "Unauthorized"}. If the user exists but lacks the API User permission, the response is 403 Forbidden. Token rotation is manual — Gladly does not enforce automatic expiration, but if the API user's account is deactivated or their email changes, the token stops working immediately.

Method 2: The REST API (Per-Entity Extraction)

Best for: Targeted extraction of specific customers, conversations, or conversation items. Useful for incremental syncs, validation scripts, and small-to-mid-size datasets.

The REST API uses token-based Basic Auth. The user creating the token needs the API User permission. Gladly recommends a dedicated API user rather than reusing a working agent account — if the user behind a token is deactivated, integrations using that token stop working immediately without warning.

Customer Profiles

Search by email, phone number, or external customer ID:

GET /api/v1/customer-profiles?email=customer@example.com

Returns up to 50 profiles, sorted by most recently updated. No pagination — if your query matches more than 50 customers, you get the first 50 and lose the rest silently.

Conversations per Customer

GET /api/v1/customers/{customerId}/conversations

Returns at most 100 conversations, in ascending timestamp order. Not paginated. If a customer has more than 100 conversations, the response is silently truncated. The Gladly-Limited-Data response header will be set to true — but there is no query parameter, cursor, or offset mechanism to retrieve the remaining conversations through this endpoint.

Reconciliation workflow when truncation is detected:

1. Identify customers where REST API calls return Gladly-Limited-Data: true.
2. Cross-reference those customer IDs against your Export API conversation_items.jsonl data, which captures all delivered items within the date range regardless of per-customer truncation limits.
3. The Export API data is the ground truth for completeness. Any conversations present in the Export API but absent from the REST API response are the truncated records.
4. Log the delta and flag these customer IDs for manual validation.

A raw truncated response header looks like this in context:

HTTP/1.1 200 OK
Content-Type: application/json
Gladly-Limited-Data: true
Ratelimit-Limit-Second: 10
Ratelimit-Remaining-Second: 9

[{"id": "conv1", ...}, {"id": "conv2", ...}]

Conversation Items

GET /api/v1/conversations/{conversationId}/items

Returns at most 1,000 items per conversation, ascending by timestamp. Not paginated. The Gladly-Limited-Data header flags truncation. There is no filtering by item type or date range available on this endpoint.

Other Useful REST Endpoints

Rate limit error response (429):

HTTP/1.1 429 Too Many Requests
Ratelimit-Limit-Second: 10
Ratelimit-Remaining-Second: 0
 
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 1 second."
}

Method 3: The Reports API (Operational CSV Export)

Best for: Exporting operational metrics, agent performance data, contact center analytics, and conversation-level metadata as CSV.

Gladly's Reports API generates the same reports available in the UI, returned as CSV. Use it for extracting structured metadata (timestamps, durations, SLA data, inbox assignments) rather than raw message content.

curl -X POST -u user@org.com:$TOKEN \
  https://org.gladly.com/api/v1/reports \
  -H "Content-Type: application/json" \
  -d '{
    "metricSet": "ConversationExportReport",
    "timezone": "America/Los_Angeles",
    "startAt": "2026-07-01",
    "endAt": "2026-07-31",
    "aggregationLevel": "daily"
  }'

Gladly offers 40+ metric sets including ContactExportReportV3, ConversationExportReport, AgentSummaryV2, WorkSessionsReportV3, TaskExportReport, and TopicSummaryReport.

Reports can also be exported as CSV directly from the Gladly UI. Some reports support up to 1 million rows in CSV export, while others cap at 100,000 rows. The CSV contains raw data — percentages appear as decimals, durations as seconds — so expect formatting work downstream.

Reports API rate limits are stricter than standard endpoints: 10 requests per minute with a maximum of 2 concurrent requests across the entire organization. If two engineers both fire report generation requests simultaneously, the third request is rejected immediately with a 429.

Rate limit error response for Reports API (concurrent limit exceeded):

HTTP/1.1 429 Too Many Requests
 
{
  "error": "Too Many Requests",
  "message": "Maximum concurrent report requests exceeded. Please wait for existing requests to complete."
}

Plan report extraction sequentially. If you are automating multiple report pulls, add a completion check between requests rather than firing them in parallel.

A note on the Contact Export report specifically: it is grouped by contact and anchored on queued at, includes fields like Customer ID, Conversation ID, Channel, inbox values, agent-at-end, durations, and message counts. It only includes contacts that were actually queued — auto-closed contacts appear in Contact Timestamps instead. Contact Export contains data from January 1, 2025 onward by default, with older data available through Support.

Use reports for metrics and operational analysis — not as your primary conversation-history extract.

Method 4: The Events API (Near-Real-Time Stream)

Best for: Capturing live event streams for real-time sync, audit logs, or triggering downstream workflows.

The Events API returns a JSONL stream of events for specified entity types within a time range.

GET /api/v1/events?startAt=2026-08-01T00:00:00Z&entities=CONVERSATION&entities=CUSTOMER_PROFILE

Constraints:

• Events are available for the past 24 hours only
• Events are up to 15 seconds behind real-time
• Supported entity types: AGENT_AVAILABILITY, AGENT_STATUS, CONTACT, CONVERSATION, CUSTOMER, CUSTOMER_PROFILE, PAYMENT_REQUEST, TASK

The Events API is not a substitute for the Export API — it is a complement. Use it for incremental delta syncs after an initial bulk extraction. Gladly also supports webhooks for conversation status changes, assignee updates, and customer merges, but limits organizations to 20 webhooks total.

Gladly API Rate Limits: Complete Reference

Rate limits apply per organization, not per API token. All tokens from your org share the same quota.

Exceeding limits returns a 429 status code. The response headers Ratelimit-Limit-Second and Ratelimit-Remaining-Second let you monitor your remaining quota in real time.

Practical throughput ceiling: At 10 GET requests per second with an average network round-trip of 150ms, extracting 50,000 conversation items individually (one REST API call per item) takes roughly 83 minutes of pure API time — before accounting for retry overhead, downstream processing, or attachment retrieval. This calculation assumes no 429s and perfect scheduling. In practice, budget 2–3x that figure for a realistic extraction job at this scale. This is why the Export API exists for bulk operations.

Conversation Item Content Type Schemas

The content.type field in each conversation item determines the schema of the content object. A parser must handle all eleven types or it will fail silently on unrecognized records. Below are the schemas for each type.

CHAT_MESSAGE

{
  "type": "CHAT_MESSAGE",
  "sessionId": "5k04bYuTRGqyT6uoSQfWVA",
  "content": "Hi! Can someone help with my order?"
}

EMAIL

{
  "type": "EMAIL",
  "from": {"name": "Jane Smith", "email": "jane@example.com"},
  "to": [{"name": "Support", "email": "support@company.com"}],
  "cc": [],
  "bcc": [],
  "subject": "Order #12345 issue",
  "bodyText": "Plain text body...",
  "bodyHtml": "<p>HTML body...</p>",
  "messageId": "<msg-id@mail.example.com>",
  "inReplyTo": null,
  "attachmentIds": ["attachmentId1", "attachmentId2"]
}

PHONE_CALL

{
  "type": "PHONE_CALL",
  "direction": "INBOUND",
  "durationSeconds": 342,
  "endpointId": "endpoint-id",
  "from": "+15551234567",
  "to": "+18005550100",
  "recordingAvailable": true,
  "transcriptAvailable": true,
  "sipCallId": "sip-call-id-string"
}

VOICEMAIL

{
  "type": "VOICEMAIL",
  "durationSeconds": 45,
  "from": "+15551234567",
  "to": "+18005550100",
  "recordingAvailable": true,
  "transcriptAvailable": false
}

SMS_MESSAGE

{
  "type": "SMS_MESSAGE",
  "direction": "INBOUND",
  "from": "+15551234567",
  "to": "+18005550100",
  "body": "Is my package shipped yet?",
  "attachmentIds": []
}

CONVERSATION_NOTE

{
  "type": "CONVERSATION_NOTE",
  "body": "Customer called to ask about return policy. Resolved.",
  "bodyHtml": "<p>Customer called to ask about return policy. Resolved.</p>"
}

CONVERSATION_STATUS_CHANGE

{
  "type": "CONVERSATION_STATUS_CHANGE",
  "status": "RESOLVED",
  "previousStatus": "OPEN"
}

TOPIC_CHANGE

{
  "type": "TOPIC_CHANGE",
  "topicId": "topicId123",
  "action": "ADDED"
}

CUSTOMER_ACTIVITY

{
  "type": "CUSTOMER_ACTIVITY",
  "activityType": "PAGE_VIEW",
  "url": "https://shop.example.com/products/widget",
  "title": "Widget Product Page"
}

FACEBOOK_MESSENGER_MESSAGE

{
  "type": "FACEBOOK_MESSENGER_MESSAGE",
  "direction": "INBOUND",
  "body": "Hello, I have a question.",
  "pageId": "fb-page-id"
}

VOICE_AI_MESSAGE

{
  "type": "VOICE_AI_MESSAGE",
  "role": "ASSISTANT",
  "content": "Thank you for calling. How can I help you today?"
}

Parser implementation note: Fields like attachmentIds, recordingAvailable, and transcriptAvailable determine whether additional REST API calls are needed to retrieve binary assets. Build your parser to extract these flags and queue supplemental retrieval jobs accordingly, rather than making attachment API calls unconditionally for every item.

Handling Attachments and Binary Assets

Attachments, call recordings, and voice transcripts are not embedded in the Export API's JSONL files. They require separate retrieval through the REST API:

• Attachments: GET /api/v1/conversation-items/{id}/attachments/{attachmentId} responds with 303 See Other. The Location header contains a time-limited pre-signed URL. Follow the redirect with your HTTP client, or extract the URL and download separately. Pre-signed URLs expire — download immediately after retrieval.
• Call recordings: GET /api/v1/conversation-items/{id}/media/recording returns the audio binary directly.
• Voice transcripts: GET /api/v1/conversation-items/{id}/voice-transcript returns the transcript text.

There is no bulk download endpoint for any of these. Each must be retrieved per conversation item, a constraint you will also encounter when exporting data from Freshchat.

Practical workflow for attachments:

1. Parse the Conversation Item JSONL for items where content.attachmentIds is non-empty, or content.recordingAvailable / content.transcriptAvailable is true.
2. Extract the item and attachment IDs.
3. Issue a GET request, follow the 303 redirect, and download the binary file.
4. Re-host the file on your own infrastructure or upload directly to your target system.
5. Rewrite URLs in the message body to point to the new location.

Build in timeout handling and retry logic for large video or audio recordings. Call recordings for long support interactions can exceed 100MB. Voice calls of 5+ minutes often have recordings exceeding 10MB — set your HTTP client timeout to at least 120 seconds per file.

What You Cannot Export from Gladly

These are the known portability gaps — functionality that exists in Gladly but has no API export path:

• No bulk customer email export from the UI. Use the REST API or request a one-time paid CSV from Gladly Professional Services.
• Conversation transcripts are not available in the UI. API-only retrieval.
• Routing rules, SLA configurations, IVR logic, and workflow automations are not exposed via API. These must be manually documented and rebuilt in any target system.
• Custom Sidekick (AI) configurations are not exportable.
• Help Center content can be retrieved via the Public Answers API, but the hierarchical structure (sections, ordering) requires manual reconstruction.
• Call recordings and voicemails must be downloaded individually per conversation item — no bulk endpoint.
• API export job scheduling cannot be configured programmatically. Hourly and one-time jobs require contacting Gladly Support.

Gladly also offers a beta API Export Tool — a web-based GUI wrapping parts of the REST API for configuration exports, conversation exports, and logs. It is useful for audits and spot checks but not suitable as the primary extraction mechanism for high-volume migration or warehouse integration, since it does not expose the full parameter control available through the underlying APIs directly.

Translating Gladly's Person-Centric Data to Tickets

If you are migrating from Gladly (or similar person-centric platforms like Kustomer) to a ticket-centric platform (Zendesk, Freshdesk, Intercom, HappyFox), your biggest engineering challenge is breaking the lifelong customer timeline into discrete ticket records. (If you are moving in the opposite direction, see our Intercom to Gladly migration guide for how to handle this translation in reverse.)

Gladly does not enforce strict ticket boundaries. You must define algorithmic rules in your extraction middleware to group Conversation Items into tickets.

Common timeline-splitting strategies:

1. Split by Gladly Conversation ID: The simplest method. Treat each Gladly conversationId as a distinct ticket. The risk: if agents rarely closed conversations, you end up with massive, multi-year tickets that exceed target system payload limits.
2. Split by time inactivity: Group items into a ticket until there is a 7-day or 14-day gap in customer communication. After the gap, generate a new ticket ID. This mirrors how most helpdesks auto-close tickets.
3. Split by channel: Isolate distinct SMS threads, email chains, and chat sessions into separate tickets based on content.type and session identifiers.

In practice, splitting by Gladly Conversation ID first — with a time-inactivity rule as a fallback for conversations that exceed target system payload limits — is the most reliable approach. Most ticket-centric platforms cap individual ticket sizes between 500KB and 5MB; a multi-year Gladly conversation with hundreds of items and embedded attachments will exceed these limits.

Dealing with Redacted Data

When an agent redacts a credit card number or other PII in Gladly, the original text is permanently destroyed. In the export payload, redacted items are replaced with tombstone markers or redaction tags. Do not attempt to reconstruct redacted data. Map the redaction marker to your target system's equivalent field so the historical context of the redaction is preserved — most helpdesks support a redaction comment or internal note type that can hold this marker.

Step-by-Step: Full Data Extraction from Gladly

Step 1: Audit Your Data Scope

Before writing any code:

• How many customers? (Check via the Contact Export report)
• Date range needed? (Full history vs. last N months)
• Do you need call recordings and attachments, or text only?
• Are there customers with 100+ conversations who will hit truncation limits?
• Do you need operational metadata (SLA times, handle times) from the Reports API in addition to raw conversation content?

Step 2: Create a Dedicated API User

Create a dedicated API user in Gladly rather than reusing an agent account. Assign the API User permission, generate the token, and store it in a secrets manager (not in environment variables or source code). Document the API user's email address separately — if it needs to change, all dependent tokens must be regenerated. If the user behind a token is deactivated, all integrations using that token stop working immediately with 401 Unauthorized.

Step 3: Request Historical Export Files

If you need data older than 14 days, contact Gladly Support to regenerate export files for your full date range before starting. Budget several business days — it is not instant, and exports covering more than six months may incur a service fee. Get written confirmation of the date ranges Gladly will regenerate before proceeding.

Step 4: Download and Parse Export API Files

Pull customers.jsonl, conversation_items.jsonl, agents.jsonl, and topics.jsonl. Parse JSONL line by line — do not load the entire file as a JSON array. For large tenants, conversation_items.jsonl may be several gigabytes.

import json
 
customers = []
with open('customers.jsonl', 'r') as f:
    for line in f:
        line = line.strip()
        if line:  # skip blank lines
            customers.append(json.loads(line))

Step 5: Export Reference Data

Pull reference objects via the REST API: topics, inboxes, audiences, agents, and answers. These give you the lookup tables needed to decode IDs and preserve business meaning in the exported data.

Step 6: Enrich with REST API Where Needed

The Export API does not include everything. If you need:

• Conversation metadata (assignee, inbox, status): GET /api/v1/conversations/{conversationId}
• Attachments: GET /api/v1/conversation-items/{itemId}/attachments/{attachmentId} (follow 303 redirect immediately; pre-signed URLs are time-limited)
• Voice transcripts: GET /api/v1/conversation-items/{itemId}/voice-transcript
• Call recordings: GET /api/v1/conversation-items/{itemId}/media/recording

Batch these requests against the 10 req/second limit. Pace at 8–9 req/second in production to maintain a buffer.

Step 7: Export Operational Metadata via Reports API

Use the Reports API to pull ConversationExportReport and ContactExportReportV3 for structured metadata — SLA timestamps, handle times, channel breakdowns — that the Export API files do not capture. Run these sequentially, not in parallel, to avoid hitting the 2-concurrent-request ceiling.

Step 8: Validate Against Truncation Limits

For any customer where the Gladly-Limited-Data: true header appeared during REST API calls, cross-reference against your Export API data. The Export API captures all delivered items within the date range, so it serves as your ground truth for completeness. Log every customer ID where this header appears and resolve the delta before cutover.

Step 9: Verify Record Counts

Compare extracted counts to Gladly's built-in Conversation Summary Report. Keep a ledger of:

• Every response where Gladly-Limited-Data: true appeared and how it was resolved
• Every 301 merge redirect and the old-to-new customer ID mapping
• A sample of report rows cross-referenced against transcript history for the same customers

Gladly documents that export jobs may exclude conversation items with invalid attributes in rare cases. Build in a reconciliation step that flags count discrepancies above a configurable threshold (e.g., >0.1% variance) for manual review.

Data Format Reference

Each line in conversation_items.jsonl is a JSON object with this top-level structure:

{
  "id": "ybP4szYCSy6LdV4DNwEd6g",
  "conversationId": "9BcE2O0DQ2ynGHRmk9FeoA",
  "customerId": "OOrlNMXeS72gs_WEX2TtMg",
  "timestamp": "2026-07-01T11:46:45.010Z",
  "initiator": {
    "id": "OOrlNMXeS72gs_WEX2TtMg",
    "type": "CUSTOMER"
  },
  "content": {
    "type": "CHAT_MESSAGE",
    "sessionId": "5k04bYuTRGqyT6uoSQfWVA",
    "content": "Hi! Can someone help with my order?"
  }
}

The initiator.type field can be CUSTOMER, AGENT, or SYSTEM. System-initiated items are internal events and typically should not be surfaced as customer-facing messages in a target system.

The complete list of content.type values is: CHAT_MESSAGE, EMAIL, PHONE_CALL, SMS_MESSAGE, VOICEMAIL, CONVERSATION_NOTE, CONVERSATION_STATUS_CHANGE, TOPIC_CHANGE, CUSTOMER_ACTIVITY, VOICE_AI_MESSAGE, and FACEBOOK_MESSENGER_MESSAGE. See the schema section above for the field definitions of each type.

GDPR and Compliance

Gladly supports CCPA and GDPR data subject requests through its Compliance Administrator role. In the Gladly UI, you can open a customer's profile and use Export Customer Profile to download a JSON file that can be shared with the requesting individual. This is a single-customer path — it is not a tenant-wide export.

Users with the Compliance Administrator role can delete individual customer profiles and all associated data from the UI. Gladly retains non-PII identifiers (Contact IDs, Customer IDs, Conversation IDs) after deletion to preserve reporting continuity. Gladly's compliance docs note that deleting a profile removes data stored in Gladly but does not delete source data in connected systems such as Shopify.

For GDPR Article 20 portability requests: Use the REST API GET /api/v1/customers/{id} combined with GET /api/v1/customers/{id}/conversations and per-conversation item retrieval to assemble a complete machine-readable export for the individual. The Export API's JSONL format is machine-readable and satisfies Article 20's "structured, commonly used, machine-readable format" requirement. There is no self-service portal for end consumers to download their own data — your team must process these requests manually using the API, and the 100-conversation truncation limit applies here too.

When to Use Which Method

If you are exporting as part of a migration, see our guides for specific targets: Gladly to Freshdesk, Gladly to Intercom, Gladly to Zendesk, or the Gladly Migration Checklist.