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

Help Scout does not have an "Export Everything" button. The built-in UI export covers reporting metrics only — conversation volume, response times, happiness scores — delivered as CSV or XLSX. It explicitly excludes conversation thread contents, message bodies, and satisfaction rating comments. (docs.helpscout.com)

If you need the actual text of your support conversations, customer records, attachments, or knowledge base articles, you must use the API or a third-party tool.

The gap between what the UI gives you and what you actually need is enormous. The UI export is fine for a quarterly board deck. It is not a migration tool.

For a migration-ready export, treat Help Scout as three separate data surfaces: report exports in the app, inbox data in the Inbox API 2.0, and knowledge base content in the Docs API. The Inbox API is JSON over HTTPS with OAuth 2.0. The Docs API uses per-user API keys over HTTP Basic auth. (developer.helpscout.com)

This guide covers every extraction method available, what each one actually returns, and the exact rate limits, pagination rules, and authentication constraints you will hit along the way.

If you are exporting specifically to migrate to another platform, these destination-specific guides cover field mapping and import constraints: Help Scout to Zendesk, Help Scout to Freshdesk, or Help Scout to Intercom.

What Data Can You Export from Help Scout?

Before choosing an export method, understand what Help Scout considers exportable and which extraction path covers each data type.

The key takeaway from this table: there is no single method that extracts everything. A complete export requires combining at least the Inbox API (for conversations, customers, and users) with the Docs API (for knowledge base articles).

Method 1: UI Report Export (CSV / XLSX)

What it is: A built-in export available from the Help Scout Reports dashboard. Select a report (All Channels, Email, Company, User, or Happiness), apply date and tag filters, and click the Export/Print icon. (docs.helpscout.com)

Step-by-step

1. Navigate to Reports in Help Scout.
2. Select the report type (e.g., All Channels, Email, Company, Happiness).
3. Apply filters: date range, mailbox, tags, or custom views.
4. Click the Export/Print icon near the date filter and choose Export.
5. Confirm the date range and select the format: CSV or XLSX.
6. Help Scout queues your request and emails you a download link with the subject "Data export from Help Scout."
7. Log in with the same user account that initiated the export to download the file.

What you get

• Conversation-level metadata: subject, status, assignee, created/closed dates, tags, custom fields (Plus+).
• Customer name and email associated with each conversation.
• Resolution times and response metrics.

What you don't get

• No conversation thread contents. No message bodies, no replies, no internal notes.
• No satisfaction rating comments. You get the score, not the text.
• No attachments.

This export is useful for audits, board reporting, and high-level analytics. It is useless for migration — a CSV without message bodies is not importable by any target helpdesk. Multiple export requests are queued and processed one at a time, and large exports can time out.

If you are tempted to use these CSVs as your migration dataset, read Using CSVs for SaaS Data Migrations first. It explains exactly where flat files break down for relational support data.

Method 2: Customer List via Support Request

Help Scout's support team can provide account owners with a CSV file containing names and email addresses of all customers in the account. (docs.helpscout.com)

What it includes: Customer names and email addresses.

What it does not include: Conversation history, phone numbers, custom properties, or any relational data. You get no customer IDs, no conversation counts, and no way to link contacts back to their tickets.

This is useful for a quick contact list for a CRM import. It is not migration-grade.

Method 3: The Help Scout Inbox API (Full Programmatic Export)

This is the only way to get complete conversation data out of Help Scout — including message bodies, internal notes, attachments, customer profiles, and custom fields. (developer.helpscout.com)

Authentication

The Inbox API 2.0 uses OAuth 2.0. Two flows are available:

• Client Credentials flow — for internal scripts. No user redirect required. You provide your app_id and app_secret directly.
• Authorization Code flow — for apps used by other Help Scout users.

To create credentials:

1. Go to Your Profile → My Apps in Help Scout.
2. Click Create My App and provide a name and redirect URL.
3. Copy your App ID and App Secret.

# Client Credentials flow — get an access token
curl -X POST https://api.helpscout.net/v2/oauth2/token \
  --data 'grant_type=client_credentials' \
  --data 'client_id={app_id}' \
  --data 'client_secret={app_secret}'

The response includes an access_token and expires_in of 172800 seconds (48 hours). (developer.helpscout.com)

Rate Limits by Plan

All API keys on the same account share the same rate budget: (docs.helpscout.com)

Plus plans can purchase an API Rate Limit Increase add-on ($100/month) to bump the limit to 800 calls/min.

When you hit the limit, the API returns HTTP 429 with a Retry-After header telling you how many seconds to wait. Your script must respect this header, or you will get stuck in a retry loop.

Pagination

Most list endpoints return 50 items per page, but List Conversations returns only 25 per page. (developer.helpscout.com) If you are pulling years of mailbox history, that difference changes run time significantly.

One easy miss: /v2/conversations defaults to status=active. If you want full history, you must explicitly request status=all. The documented statuses are active, all, closed, open, pending, and spam — there is no deleted status filter on the normal conversation export path. (developer.helpscout.com)

What a Full Export Looks Like

Extracting complete conversation data requires multiple API calls per conversation:

1. List all conversations — GET /v2/conversations?status=all&mailbox={id} — paginated at 25 per page.
2. For each conversation, list threads — GET /v2/conversations/{id}/threads — this is where the actual message bodies live.
3. For each thread with attachments, download each attachment — the API exposes both a binary file endpoint (/file) and a base64 data endpoint (/data).
4. List all customers — GET /v2/customers or GET /v3/customers — paginated.
5. List all users — GET /v2/users — paginated.

# Pseudocode: Export all conversations with threads
import requests
import time
 
BASE_URL = "https://api.helpscout.net/v2"
headers = {"Authorization": f"Bearer {access_token}"}
 
def fetch_all_pages(url, params=None):
    results = []
    page = 1
    while True:
        resp = requests.get(url, headers=headers, params={**(params or {}), "page": page})
        if resp.status_code == 429:
            time.sleep(int(resp.headers.get("Retry-After", 10)))
            continue
        data = resp.json()
        results.extend(data.get("_embedded", {}).get(list(data["_embedded"].keys())[0], []))
        if page >= data["page"]["totalPages"]:
            break
        page += 1
    return results
 
# Step 1: Get all conversations
conversations = fetch_all_pages(f"{BASE_URL}/conversations", {"status": "all"})
 
# Step 2: For each conversation, get threads
for convo in conversations:
    convo["threads_data"] = fetch_all_pages(
        f"{BASE_URL}/conversations/{convo['id']}/threads"
    )

Thread Types Matter

Help Scout distinguishes customer, message, note, chat, phone, lineitem, and forward thread types. If you drop note threads, you lose internal context. If you drop lineitem threads, you lose operational history like assignment and status changes. Make sure your extraction script captures all thread types, not just customer-facing messages. (developer.helpscout.com)

If you need raw email fidelity, Help Scout also exposes a per-thread RFC 822 original source endpoint.

The Math: API Calls for a Real Export

For an account with 10,000 conversations, an average of 6 threads each, and 2,000 attachments:

• List conversations: 10,000 / 25 per page = 400 requests
• List threads: 10,000 conversations × 1 request each = 10,000 requests (assuming most fit in one page)
• Download attachments: 2,000 requests
• Total: ~12,400 requests minimum

On the Standard plan (200/min), that is 62 minutes of continuous, rate-limited API calls — assuming zero retries and no 429 errors. On Plus (400/min), it drops to ~31 minutes. Real-world runs take longer because of burst limits, token refreshes, and occasional timeouts.

Useful Query Patterns

Help Scout's query language supports targeted and incremental pulls: (developer.helpscout.com)

• Full history from one inbox: mailbox=123&status=all
• Incremental export: modifiedSince=2026-03-01T00:00:00Z
• Conversations with attachments: query=(attachments:true)
• Conversations by customer ID: query=(customerIds:100)
• Conversations by replying users: query=(replyUserIds:(23 OR 45))

These filters are good enough for staged cutovers — use modifiedSince for delta pulls instead of re-pulling the entire account each time.

Customer Export: v2 vs v3 Trade-Off

Help Scout offers two customer endpoints with a real trade-off: (developer.helpscout.com)

• /v2/customers — page-based pagination, supports mailbox filtering. Better when you need to scope exports to specific mailboxes.
• /v3/customers — cursor-based pagination, no mailbox filtering. Recommended by Help Scout for better performance on large datasets.

If you use Help Scout's newer contact/company model, export both customer properties and organizations. Help Scout supports up to 50 contact properties and 50 company properties. (docs.helpscout.com)

Pros

• Complete data: The only way to get full thread content, internal notes, and attachments.
• JSON format: Structured, machine-readable, preserves relationships.
• Filterable: Query by status, mailbox, date range, tags, and custom fields.
• Incremental exports: modifiedSince support enables delta pulls for staged cutovers.

Cons

• Requires developer time to build, test, and maintain the script.
• Token expiration and rate limits require careful engineering.
• Attachments are returned as base64 or binary — you must decode, name, and re-associate them with the correct thread.
• No bulk export endpoint — it is always paginated, per-conversation.

Method 4: Help Scout Docs API (Knowledge Base Export)

The Docs API is a separate API from the Inbox API, with different authentication and rate limits. (developer.helpscout.com)

• Base URL: https://docsapi.helpscout.net/v1/
• Authentication: API key via HTTP Basic Auth (not OAuth). Find your Docs API key under Your Profile → Authentication → API Keys.
• Rate limit: Based on the number of Docs sites on your account, measured per 10-minute window.

You can export:

• Sites — List all Docs sites.
• Collections — List collections within a site.
• Categories — Categories within collections.
• Articles — Full article content (HTML body, title, slug, status, timestamps). The article list response is abbreviated, so you must fetch full article bodies from the individual article endpoint.

# List all articles in a collection
curl -u {DOCS_API_KEY}:X \
  https://docsapi.helpscout.net/v1/collections/{collection_id}/articles

Pros: Straightforward API key auth — no OAuth dance. Returns full HTML article content.

Cons: Separate API from the Inbox API — requires a second script or integration. Images embedded in articles are hosted on Help Scout's CDN; you must download and re-host them for a migration. Still paginated, no bulk export.

Method 5: ETL / No-Code Connector Tools

Tools like Coupler.io, Skyvia, Hevo Data, and Fivetran can connect to the Help Scout API and sync data to Google Sheets, CSV, BigQuery, or a data warehouse. (skyvia.com)

What they are good for

• Scheduled reporting syncs — pull conversation metadata into a BI tool on a recurring basis.
• Building dashboards without writing custom scripts.
• Quick one-time pulls of specific data types.

What they struggle with

• Token expiration. The 48-hour token limit means scheduled syncs can break silently if the tool does not handle refresh tokens properly. Coupler's own Help Scout guide calls this out as a drawback for long-running recurring exports. (blog.coupler.io)
• Thread-level data. Most connectors pull conversation-level metadata, not the individual thread bodies. You may need custom configuration to fetch threads per conversation.
• Attachment download. No-code tools typically cannot download binary attachment data and re-associate it with conversations.
• Migration readiness. The output is a flat table, not a relational dataset. Thread order, inline images, and parent-child relationships between conversations and threads are lost or flattened.

Use ETL tools when you need scheduled extracts for BI or ad hoc CSVs for stakeholders. Do not use them as your migration plan when you need thread reconstruction, attachment re-linking, or audit-grade QA.

Method 6: Automated Migration Services

Self-service migration vendors like Help Desk Migration (Relokia) offer wizard-based tools that read from Help Scout's API and write directly to a target platform. They handle conversations, customers, attachments, and agents. (help-desk-migration.com)

What they handle well

• Conversation metadata, thread content, and attachments.
• Agent and customer mapping to the target platform.
• A demo migration to preview results before committing.

Where they fall short

• Custom field mapping is often limited or requires manual configuration.
• Inline images (images embedded in message bodies, not as file attachments) may not transfer correctly. Help Desk Migration's own Help Scout checklist documents cases that need personalized handling. (help-desk-migration.com)
• Workflows, automations, and saved replies are not migrated — those must be rebuilt manually.
• Per-record pricing makes it hard to predict total cost. For accounts with 50,000+ tickets, costs scale aggressively.

Engineer-Led Migration (ClonePartner)

ClonePartner manages the entire extraction infrastructure — API orchestration, token management, attachment handling, and field mapping to your target platform. Unlike automated tools that charge per-ticket, we offer predictable pricing and guarantee exact preservation of inline attachments, threaded conversation history, and custom fields.

For destination-specific guidance:

• Help Scout to Zendesk
• Help Scout to Freshdesk
• Help Scout to Intercom

The Hidden Challenge: Exporting Attachments and Inline Images

Attachments are where Help Scout exports stop being easy. They are stored at the thread level, not the conversation level. Each thread can contain multiple attachments, and each must be downloaded individually via the API.

The List Threads endpoint includes an _embedded.attachments array with metadata (filename, mimeType, size) and links to the download endpoint. The process looks like this: (developer.helpscout.com)

1. Parse the attachment metadata from each thread.
2. Call the download endpoint for each attachment. The API exposes both a binary file endpoint (/file) and a base64 data endpoint (/data). Use the binary endpoint when your target system expects a file stream; use the data endpoint when a downstream process expects base64.
3. Decode and store the file with a naming convention that preserves the conversationId → threadId → attachmentId relationship.

Inline images are a different problem entirely. Images pasted directly into the message body are typically hosted on Help Scout's CDN and referenced as <img> tags in the HTML thread body. They are not listed in the attachments array. To preserve them:

1. Parse the HTML body of each thread.
2. Extract all <img src="..." /> URLs pointing to Help Scout's CDN.
3. Download each image.
4. Re-host the images on your own storage (like AWS S3) and replace the URLs in the HTML body with the new location.

If you skip this step, your migrated conversations will contain broken image links once Help Scout purges or restricts access to the CDN assets.

One more nuance worth noting: custom fields and contact/company properties are not the same thing in Help Scout. Custom fields are inbox-specific conversation fields. Contact and company properties are global profile data. Export both if you want to preserve context cleanly. (docs.helpscout.com)

Pre-Export Checklist: Preparing Your Help Scout Data

Before pulling any data, clean up your source. It is cheaper to fix data issues in Help Scout than in your export pipeline.

1. Audit and consolidate tags

Remove duplicate or unused tags. Standardize naming conventions (decide between bug-report, Bug Report, and bug_report). Tags export as plain strings — inconsistencies carry over to your target system.

2. Verify custom field configurations

Custom fields are only available on Plus plans and above. Document every custom field name, type, and dropdown option. The API returns field IDs, not labels, in some contexts — you will need the mapping. Custom fields belong to a single mailbox; if a conversation is moved to another mailbox, the custom-field data does not carry over even if the field name matches. (developer.helpscout.com)

3. Map users and agents

List all active and deactivated users. Deactivated users still own historical conversations and must be mapped to the target system — either to their corresponding new profile or to a generic "Legacy Agent" account. See How to Migrate Users & Organizations Without Breaking History for the full playbook.

4. Identify your mailboxes and scope

If you have multiple mailboxes, decide which ones to export. Each mailbox has its own ID, and conversations are filtered by mailbox in the API.

5. Count conversations and estimate API time

Use the Reports dashboard to get a rough count of total conversations. Apply the math from Method 3 to estimate how long the extraction will take on your plan.

6. Check for merged conversations

Merged conversations redirect to the surviving conversation via HTTP 301 for 60 days, then return 404. If you have recently merged conversations, export sooner rather than later.

7. Capture saved replies

Saved replies are listable via the API (use includeChatReplies=true to capture chat-only replies), but importing them into another platform typically requires manual recreation. Extract them before decommissioning your Help Scout account.

8. Plan for Docs separately

If your knowledge base matters, set up the Docs API export as a distinct step with its own authentication and rate limit budget.

9. Use status=all and modifiedSince deliberately

Do not rely on the default active filter when you want full history. For staged cutovers, use modifiedSince for delta pulls instead of re-pulling the entire account.

10. Validate counts before calling the export complete

Compare page totals or cursor counts, spot-check attachments and threads, and confirm IDs and mappings before importing anything into the target system.

What Cannot Be Exported from Help Scout

Some data types are either completely inaccessible or require workarounds:

Choosing the Right Export Method

For a full migration — moving to Zendesk, Freshdesk, Intercom, or another helpdesk — the UI export and ETL tools are not enough. You need the Inbox API for conversations and threads, the Docs API for knowledge base articles, and a plan for attachments and inline images. That is a minimum of two API integrations, token refresh logic, rate-limit handling, and a data pipeline that preserves relational integrity.

When to Bring in Engineers

If your Help Scout account has more than a few thousand conversations, the API-based export becomes a legitimate engineering project. Token management, rate-limit throttling, attachment download and re-association, inline image handling, and data validation all take time to get right — and they all have failure modes that silently corrupt your data.

If you only need a report export, do it yourself. If you only need a BI feed, use an ETL tool. But if you need a defensible dataset that another system can actually ingest without losing context, get engineers involved.

At ClonePartner, we have run hundreds of helpdesk migrations, including many from Help Scout. We handle the full extraction pipeline — API orchestration, attachment management, thread-level fidelity, and field mapping to your target platform — with zero downtime guaranteed. If you would rather not spend two weeks writing and debugging export scripts, we will have your data out in days.

For a deeper look at how we approach helpdesk moves, see How We Run Migrations at ClonePartner.