How to Export Data from Gorgias: Methods, API Limits & Formats

How to Export Data from Gorgias: Methods, API Limits & Formats

Gorgias gives you four ways to get data out: CSV exports from ticket views (metadata only), analytics drill-down CSVs (with message content for the last 30 days), the REST API for full programmatic extraction, and custom exports via Gorgias support for edge cases. There is no single-click full-account export—a limitation it shares with other platforms like Groove.

The right method depends on what you need. A reporting audit and a platform migration are fundamentally different jobs, and Gorgias treats them differently. This guide covers exactly what each method can and cannot do, the API rate limits you'll hit during bulk extraction, pagination mechanics, attachment handling, and the edge cases that trip teams up during real exports. API details are verified against Gorgias developer documentation as of mid-2026 — confirm rate limits and field availability against current docs before building extraction scripts.

This blog is published by a migration services vendor. Technical content is separated from commercial recommendations structurally. If you're exporting as part of a migration, see our platform-specific guides: Gorgias to Zendesk, Gorgias to Freshdesk, or Gorgias to Intercom. For a broader look at CSV-based migrations, see Using CSVs for SaaS Data Migrations.

What Data Can You Export from Gorgias?

Unlike platforms with complex custom objects (like Kustomer), Gorgias's data model is strictly ticket-centric. Every object revolves around tickets, messages within those tickets, and the customers who created them. Here's what's exportable and how:

The UI exports cover tickets and macros. Everything else requires the API or a support request.

Method 1: CSV Export from Views (Metadata Only)

The fastest way to get ticket data out of Gorgias without writing code. Select tickets from any view in the helpdesk, click the "Export tickets" bulk action, and Gorgias emails you a download link to a CSV file sorted in the same order as the source view. (docs.gorgias.com)

What's included: Ticket ID, subject, status, priority, channel, assignee, tags, message count, created/updated/closed timestamps, customer email, CSAT, first response time, resolution time, and custom ticket/customer fields.

What's NOT included: Message bodies, internal notes, ticket events, or attachment binaries.

Limits:

• Up to 1 million tickets per export
• Processing time: roughly 1 hour per 100,000 tickets, up to 10 hours for 1 million
• Download link expires after 14 days
• Available to account owners, admins, and leads on all Helpdesk plans

When to use it: Quick audits, tag analysis, agent workload reviews, or validating ticket counts against an API extraction.

Method 2: Analytics Drill-Down Export (With Message Content)

As of May 2026, Gorgias added a self-serve option to export message content directly from analytics drill-downs — replacing the older pattern of needing the API or a support request for message bodies. (docs.gorgias.com)

How it works:

1. Go to Analytics from the top-left dropdown
2. Select a report with an exportable drill-down
3. Click a metric to open the drill-down
4. Click Export → select "Export with message content"
5. Gorgias emails you the CSV when it's ready

Limits:

• Message content exports cover the most recent 30 days of the selected period only, with a maximum of 100,000 tickets
• Public messages only — internal notes, Facebook wall posts, Instagram media messages, and Instagram ad media messages are excluded
• Metadata-only exports from the same interface cover up to 2.5 years
• Timestamps render in the timezone of the person who exported the file

This is a significant constraint for migrations. If you have 18 months of ticket history, the drill-down export only gives you the last 30 days of message text. For the rest, you need the API.

When to use it: Conversation review, support QA, or prompt analysis where a recent window is sufficient and internal notes don't matter.

Method 3: REST API (Full Programmatic Access)

The API is the only way to extract your complete Gorgias dataset — tickets, messages, customers, tags, users, macros, rules, surveys, events, and custom fields — in a structured, automatable way. Use it for platform migrations, data warehouse builds, compliance archives, or continuous sync.

Gorgias is explicit that undocumented resources should be treated as non-existing, so stay on the documented API if you want an exporter that survives platform changes. (developers.gorgias.com)

Authentication

Gorgias uses HTTP Basic Authentication for private apps. You need your Gorgias account email and API key (found under Settings → Account → REST API).

curl -u 'you@yourstore.com:YOUR_API_KEY' \
  'https://yourstore.gorgias.com/api/tickets?limit=30'

Public apps use OAuth2 instead, which doubles your request throughput (see rate limits below). Two details that frequently cause failures:

• API keys inherit the permissions of the user who created them. Exporting with a low-privilege agent account silently limits what you can read. Use an admin-level key. (developers.gorgias.com)
• If the user who created the key is deactivated, the key stops working. Tie API keys to a service account, not an individual employee.

Setting Up OAuth2 for Higher Throughput

OAuth2 is worth configuring if you have more than ~20,000 tickets. The setup path:

1. Go to Settings → REST API → Create Application to register a public app
2. Provide a redirect URI (can be localhost for internal tooling)
3. Complete the authorization code flow to obtain an access token and refresh token
4. Send Authorization: Bearer {access_token} instead of Basic Auth credentials
5. Implement refresh token rotation — access tokens expire and must be renewed

OAuth2 credentials are scoped to the app, not an individual user account, which also removes the deactivated-user problem.

Rate Limits

This is where most extraction scripts break. Gorgias uses a leaky bucket algorithm — your request budget refills steadily over time rather than resetting in one block.

The limit is per account, not per key. Your migration script, your reporting sync, your Aircall integration, and your chat widget all draw from the same bucket. Running an extraction while other integrations are active means sharing that budget. (developers.gorgias.com)

On concurrent requests: Multiple threads or processes sharing the same API credentials do not increase effective throughput — they hit the same per-account bucket simultaneously. The result is more 429 responses, not more data transferred. Parallelism only helps if you can distribute work across multiple OAuth2 applications registered under the same account, each with its own bucket.

When you exceed the limit, the API returns 429 Too Many Requests. Two response headers tell you what to do:

• Retry-After — seconds to wait before retrying
• X-Gorgias-Account-Api-Call-Limit — current usage vs. limit (e.g., 35/40)

import requests
import time
 
def gorgias_get(url, auth):
    while True:
        resp = requests.get(url, auth=auth)
        if resp.status_code == 429:
            wait = int(resp.headers.get('Retry-After', 5))
            time.sleep(wait)
            continue
        resp.raise_for_status()
        return resp.json()

Tracking API Deprecations

Gorgias signals breaking changes via their developer changelog and deprecation notices in the API reference documentation. Deprecated endpoints typically include a notice in the reference docs and may return deprecation warning headers before removal. For long-lived extractors, monitor the changelog and check response headers for any Deprecation or Sunset headers. The safest pattern is to test against the API reference on each major run and pin your extractor to documented endpoint paths only.

Pagination: Cursor-Based Only

Gorgias removed offset-based pagination in February 2024. All list endpoints now use cursor-based pagination exclusively. (developers.gorgias.com)

The response includes next_cursor and prev_cursor fields. Follow next_cursor until it returns null. Most endpoints cap limit at 100.

def paginate_all(base_url, auth, limit=100):
    results = []
    url = f"{base_url}?limit={limit}"
    while url:
        data = gorgias_get(url, auth)
        results.extend(data.get('data', []))
        next_cursor = data.get('meta', {}).get('next_cursor')
        if next_cursor:
            url = f"{base_url}?limit={limit}&cursor={next_cursor}"
        else:
            url = None
    return results

Cursor expiry and checkpoint logic: Cursors are opaque values that can expire if the pagination session is interrupted. In practice, a cursor that sits unused for several minutes may return a 400 Bad Request or 422 Unprocessable Entity rather than the next page. The safe pattern is to store the last successfully processed ticket ID (not the cursor itself) as a checkpoint. On resume, restart pagination from the beginning but skip records with IDs already processed. This is slower than resuming mid-cursor but is robust across crashes and rate-limit pauses.

One useful filtering option on GET /api/tickets: you can pass customer_id, view_id, rule_id, external_id, or up to 100 explicit ticket IDs. A scoping trick is to save the slice you want as a Gorgias view, then pass view_id to the API — ops defines the slice in the UI, engineering reuses it in the exporter. (developers.gorgias.com)

Important edge case: trashed defaults to true, so a naïve ticket pull includes trashed records unless you explicitly set trashed=false. This skews counts and produces messy imports.

Recommended Extraction Order

Extract reference data first to avoid downstream remapping:

1. GET /api/tags — Tickets reference tags by ID
2. GET /api/users — Tickets reference assignees by user ID
3. GET /api/teams — Used for routing assignments
4. GET /api/custom-fields — Field definitions needed before field values make sense
5. GET /api/customers — Customer records with channel data (email, phone, social handles)
6. GET /api/tickets — Ticket metadata, status, assignee, tags, customer reference
7. GET /api/messages — Messages for each ticket (see next section)
8. GET /api/macros — Canned responses
9. GET /api/rules — Automation rules
10. GET /api/satisfaction-surveys — CSAT data

Custom Fields: Definitions vs. Values

Gorgias separates custom field definitions from custom field values. GET /api/custom-fields returns the field schema — name, type (text, number, boolean, select, date), and which object type (ticket or customer) the field applies to. Each field has a unique id.

Custom field values are embedded in the ticket or customer object itself, not returned by a separate endpoint. In the ticket JSON, they appear under a custom_fields key as an array of {field_id, value} objects. To make these human-readable, join on the id from your custom fields extraction. Extract GET /api/custom-fields first (step 4 in the order above) and build a lookup map before processing ticket records.

Satisfaction Survey Schema

GET /api/satisfaction-surveys returns survey objects with the following key fields:

• id — Survey record ID
• ticket_id — Linked ticket
• score — Integer rating (typically 1–5 or binary satisfied/dissatisfied depending on account configuration)
• body_text — Verbatim customer comment (may be null if not provided)
• created_datetime — When the survey was submitted
• channel — Channel the ticket came through (email, chat, etc.)
• agent_id — Assigned agent at time of survey

Use ticket_id to join survey records back to ticket and customer records during transformation.

The Message Extraction Bottleneck

This is the single biggest time sink in any Gorgias export. Messages are nested inside tickets — there is no single API call that returns all messages pre-grouped by thread.

Gorgias exposes GET /api/messages which lists messages globally and supports filtering by ticket_id. The older per-ticket endpoint GET /api/tickets/{ticket_id}/messages is marked as deprecated — use the list-messages endpoint instead. (developers.gorgias.com)

For migration purposes, you almost always need messages organized by parent ticket. Whether you paginate GET /api/messages globally and group client-side, or filter per ticket_id, the API call volume is significant.

# List messages for a specific ticket using the current endpoint
curl -u agent@example.com:api_key \
  'https://your-subdomain.gorgias.com/api/messages?ticket_id=12345&limit=100&order_by=created_datetime:asc'

Realistic time estimates:

These figures are calculated from documented rate limits (40 req/20s for API Key, 80 req/20s for OAuth2), assuming one message-fetch call per ticket, no 429 errors, and no competing integration traffic. Real-world extractions typically run 20–40% slower due to shared rate limit consumption from active integrations and occasional 429 backoffs.

API call count assumes ~100 tickets per page (10–20 calls for metadata pagination) plus one message call per ticket. Accounts with high message-per-ticket ratios (e.g., complex B2B support threads) will require more calls as messages paginate within each ticket.

Attachments and Binary Data

Fetching the message JSON is not the same as archiving attached files. Attachments referenced in messages must be individually downloaded. Private files go through the Downloads API, which returns a 307 redirect to a signed URL. (developers.gorgias.com)

Extraction rules:

1. Download during extraction, not after. Attachment URLs may be temporary signed URLs that expire. Your script must download the binary and upload it to your own storage (e.g., an S3 bucket) during the extraction phase.
2. Map new URLs. When formatting data for import into the target helpdesk, replace Gorgias URLs with your newly hosted URLs.
3. Handle large files. Customer attachments can be massive (video files of defective products are common). Set appropriate HTTP client timeouts so large downloads don't crash the extraction thread.
4. Verify after download. Check that all downloaded files have a size greater than 0 bytes. Corrupted downloads are a frequent failure mode during bulk extractions.

E-commerce Metadata (Shopify, Magento)

Gorgias is known for deep e-commerce integrations, but a common misconception is that it stores order data natively. It does not.

Gorgias fetches order data dynamically from Shopify or Magento using the customer's email or phone number. When you export a ticket, the Shopify order payload is not embedded in the ticket object.

What this means: You don't need to export Shopify data from Gorgias. Preserve the customer's exact email and phone number during migration. Once data is loaded into your new system, connect that system's Shopify app and it will re-hydrate order data based on the matching email.

Macros, Rules, and Variable Translation

• Macros: Extract via GET /api/macros (or CSV export from settings). Pay close attention to body_html and body_text. Gorgias macros often contain Shopify liquid variables (e.g., {{customer.first_name}}). These variables won't work in your new system. You need a find-and-replace pass to translate Gorgias liquid syntax into the target platform's variable format.
• Rules: Extract via GET /api/rules. Rules are highly proprietary to Gorgias's execution engine. You cannot import them directly into another platform. Export them as a JSON reference file, read the logic, and manually rebuild routing and automation rules in the target platform's UI.
• Tags: Extract via GET /api/tags. Flat list, straightforward to extract. Ensure no tags are dropped during mapping — especially if your target system uses tags for routing.

Internal Notes and Audit Trail

Internal notes are a common blind spot. The analytics CSV exports public messages only, while the TicketMessage model distinguishes public content from private internal notes via a public boolean field on each message object. If notes matter in your destination system, filter for public: false messages during API extraction. (docs.gorgias.com)

For merge history, tag changes, assignment churn, or message lifecycle events, use the Events API (GET /api/events) rather than the deprecated events field on the ticket object. The Events API supports filtering by object_type, object_id, event_type, and created_datetime. Key event types include ticket-created, ticket-assigned, ticket-tagged, ticket-status-changed, and message-created. (developers.gorgias.com)

Webhook-Based Delta Sync

For zero-downtime migrations or continuous sync, webhooks let you capture changes that occur after the initial backfill starts. Gorgias supports webhooks on the following event categories:

• Ticket events: ticket.created, ticket.updated, ticket.assigned, ticket.closed
• Message events: message.created, message.updated
• Customer events: customer.created, customer.updated

Configure webhooks under Settings → Integrations → Webhooks. Each webhook delivers a JSON payload to your endpoint containing the changed object and event metadata.

Delta sync pattern for migrations:

1. Record the timestamp when your backfill starts
2. Complete the full cursor-based backfill
3. After backfill completes, query the Events API filtered by created_datetime > backfill start timestamp to find all changes during the backfill window
4. Apply those changes to your extracted dataset before loading into the target system

This approach avoids relying on webhook delivery guarantees for the reconciliation step — the Events API is more reliable than webhook delivery for gap-filling.

Method 4: Custom Export via Gorgias Support

Gorgias support can build custom exports for data points beyond self-serve exports and the standard API. Contact them with your subdomain, the data points you need, and the date range. (docs.gorgias.com)

This covers:

• Help Center articles (title, URL, content, SEO metadata) — no self-serve export path exists
• Billable ticket and revenue stats
• Agent details
• Customer notes
• Integration details

Use support exports for one-off handoffs and hard-to-reach objects. They're a weak fit for recurring syncs because the workflow is manual.

GDPR and Data Portability

Gorgias complies with GDPR as a data processor. Their Data Processing Agreement covers standard contractual clauses for EU, UK, and Swiss data transfers.

For individual customer data requests (right of access/portability), use the API to pull a specific customer's record and all associated tickets and messages. There is no one-click "export all data for this customer" button. The extraction sequence: GET /api/customers?email={email} → capture customer_id → GET /api/tickets?customer_id={customer_id} → GET /api/messages?ticket_id={ticket_id} for each ticket.

For deletion requests, deleting a customer profile in Gorgias removes their data from the platform but does not cascade to connected apps like Shopify, Klaviyo, or other integrations. Deletions in connected systems must be handled separately through each platform's own deletion mechanism.

Common Failure Modes

1. Using the view CSV as a migration source. It's fast, but it's metadata-only. You'll lose every conversation thread. (docs.gorgias.com)

2. Shared rate limit budget. Your extraction script competes with every active integration on the account. Disable non-essential integrations or schedule exports during low-traffic windows.

3. Cursor expiry. Cursors can expire if a session sits idle — in practice, pauses of more than a few minutes risk a 400 or 422 on the next page request. Build checkpoint logic that stores the last successfully processed ticket ID (not the cursor), so restarts skip already-processed records rather than replaying from a stale cursor.

4. Trashed tickets included by default. GET /api/tickets includes trashed records unless you explicitly set trashed=false. This skews counts and produces messy imports. (developers.gorgias.com)

5. Saving attachment URLs without downloading. The archive isn't complete until the binaries are fetched through the Downloads API. Signed URLs expire.

6. HTML message bodies. Email-channel messages are stored as HTML. If your target platform expects plain text, you need an HTML-to-text conversion step. Stripping HTML naively loses inline images and formatting.

7. The 30-day message content limit. The analytics drill-down with message content only covers 30 days. Teams who rely on this for migration instead of the API lose most of their conversation history.

8. Exporting with the wrong identity. API keys inherit the permissions of the user who created them. A low-privilege agent key silently limits what you can read. (developers.gorgias.com)

9. Relying on deprecated endpoints. Gorgias deprecates old paths (e.g., per-ticket message listing) and warns against using undocumented resources. Monitor the developer changelog and check for deprecation headers in responses before building long-lived extractors. (developers.gorgias.com)

10. Parallel workers against the same credentials. Multiple threads sharing one API key consume the same per-account bucket simultaneously. The result is a higher 429 rate, not higher throughput. Parallelism only helps when using multiple separately registered OAuth2 applications.

11. Misreading custom field values. Custom field values in ticket/customer objects are keyed by field ID, not field name. Without the GET /api/custom-fields lookup map, you can't interpret which value belongs to which field.

Validating Your Export

Data extraction is useless without validation. Before shutting down your Gorgias instance:

1. Ticket count parity: Compare the total from GET /api/tickets (with trashed=false) against the Gorgias UI analytics and the view CSV export. The self-serve CSV is a useful external control surface for scope checks.
2. Message integrity: Randomly sample 50–100 tickets. Compare message counts in the exported data against what's visible in the Gorgias UI. Include at least 10 tickets with internal notes to verify public: false messages were captured.
3. Attachment verification: Check that all downloaded files have size > 0 bytes. Verify a random sample by opening the files, not just checking file size.
4. Customer associations: Verify that tickets are correctly linked to customer records and that custom field values are intact after joining on field_id.
5. Delta pass: Use the Events API (GET /api/events?created_datetime [gte]={backfill_start}) to catch changes created after the backfill started. Apply these as updates before loading into the target system. (developers.gorgias.com)

Picking the Right Export Method

Summary

Exporting from Gorgias is straightforward for small datasets and metadata-only use cases. The UI exports handle those well. The moment you need full message content across your entire ticket history — the case for every real migration — you're building an API extraction pipeline with rate limiting, cursor pagination, and per-ticket message fetching.

The API is well-documented and predictable. The constraints are specific: 40 or 80 requests per 20-second window (doubled on Enterprise), no server-side date filtering, cursor-based pagination with no offset support since February 2024, messages nested inside tickets, attachments requiring separate Downloads API calls, and custom field values that require a join against field definitions to interpret.

The long tail is where complexity concentrates: internal notes (identified by public: false on the message object), attachment binaries, macro variable translation from Gorgias liquid syntax, custom field definition-to-value joins, the Events API for audit trails, and webhook or Events API delta sync for zero-downtime cutovers. That's where metadata extraction stops and engineering work begins.

Decision framework:

• Metadata audit → UI CSV export
• Recent conversation review → Analytics drill-down (30-day, public messages only)
• Complete history, all object types, migration-grade → REST API with OAuth2, extraction order as listed above, attachments via Downloads API, delta via Events API