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

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

Unthread does not offer a one-click "Export All" button. The primary — and most complete — way to export data from Unthread is through its REST API, which provides cursor-based pagination across all core objects: conversations, messages, customers, accounts, users, tags, ticket types, knowledge base articles, surveys, and reporting metrics. Every API response is JSON. If you need CSV, you transform it yourself after extraction.

Because Unthread operates as a Slack-native helpdesk, your support data has a split personality. Ticket metadata (status, assignee, priority, SLAs, custom fields) lives in Unthread, while conversation history and attachments are tightly coupled to Slack's infrastructure. Extracting data with full fidelity requires API scripts and engineering resources — not dashboard clicks.

What Data Can You Export from Unthread?

Unthread's data model centers on Conversations (the equivalent of tickets), Messages, Customers (mapped to Slack channels), Accounts (company-level groupings), Users, Tags, Ticket Types (with custom fields), Knowledge Base Articles, Surveys, Outbound Messages, and Reporting Metrics.

[For engineering] Unthread currently uses both a legacy Customer (Channel) model and a newer Account model for external organizations. If your workspace supports external customer accounts, export both — or you risk losing part of the relationship layer between people, channels, and organizations.

[For engineering] Conversation records include computed fields like responseTime, responseTimeWorking, resolutionTime, and resolutionTimeWorking — all in seconds. These are available on the conversation object but not separately aggregated unless you use the /reporting/time-series endpoint.

Unthread's documented ticket-type field types are short-answer, long-answer, single-select, multi-select, checkbox, user-select, and multi-user-select. Knowing this matters when you map Unthread data into a target schema.

API Response Structure: What the Data Actually Looks Like

Before writing extraction code, it helps to understand what the API returns. Here is a representative (truncated and anonymized) conversation object from POST /conversations/list:

{
  "data": [
    {
      "id": "conv_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "friendlyId": "TKT-1042",
      "title": "SSO login failing for enterprise users",
      "status": "closed",
      "priority": 7,
      "createdAt": "2025-11-14T09:23:41.000Z",
      "updatedAt": "2025-11-15T14:02:19.000Z",
      "closedAt": "2025-11-15T14:02:19.000Z",
      "assignedToUserId": "usr_f8e7d6c5-b4a3-2109-8765-43210fedcba9",
      "customerId": "cust_1a2b3c4d-5e6f-7890-abcd-ef0987654321",
      "channelId": "C04ABCDEF12",
      "responseTime": 342,
      "responseTimeWorking": 342,
      "resolutionTime": 103358,
      "resolutionTimeWorking": 28800,
      "tags": [
        { "id": "tag_aaa111", "name": "sso" },
        { "id": "tag_bbb222", "name": "enterprise" }
      ],
      "ticketTypeId": "tt_xyz789",
      "ticketTypeFields": {
        "fld_abc123-def456": "Production",
        "fld_ghi789-jkl012": ["High Impact"]
      },
      "summary": "User reported SSO login loop on Chrome 119...",
      "files": [
        {
          "id": "file_001",
          "name": "error-screenshot.png",
          "size": 245760,
          "filetype": "png",
          "mimetype": "image/png"
        }
      ],
      "followers": ["usr_aaa111", "usr_bbb222"],
      "metadata": {}
    }
  ],
  "totalCount": 4287,
  "cursors": {
    "hasNext": true,
    "hasPrevious": false,
    "next": "eyJjcmVhdGVkQXQiOiIyMDI1LTExLTE0VDA5OjIzOjQxLjAwMFoiLCJpZCI6ImNvbnZfYTFiMmMzZDQifQ==",
    "previous": null
  }
}

Key observations from this structure:

• ticketTypeFields is a flat object keyed by field UUID, not by human-readable label. You must join against the ticket type definitions from POST /ticket-types/list to make these meaningful.
• tags is an inline array — there is no separate tag-assignment table to export.
• responseTime and resolutionTime are in seconds. responseTimeWorking and resolutionTimeWorking reflect business-hours calculations.
• files contains metadata only. The binary content requires a separate GET call per file.
• cursors.next is a base64-encoded cursor token. Pass it back in your next request body to paginate forward.
• priority uses numeric values: 3 (urgent), 5 (high), 7 (normal), 9 (low).

Export Methods: Every Way to Get Data Out of Unthread

[For PMs] Zero-engineering options: analytics CSV for KPI reporting and BI tool integrations for dashboards. Every other method requires a developer or a third-party integration platform.

A practical rule: use analytics CSV when the question is "How did support perform?" Use the API when the question is "What exact conversations, replies, files, tags, and custom fields do we own?" Those are different jobs, and Unthread treats them differently in the product.

Native UI Export: What Exists and What Doesn't

Unthread's dashboard does not provide a "Download CSV" or "Export All" button for conversations, customers, or tickets.

What you can do from the UI:

• Analytics CSV: Go to Dashboard → Analytics, open a report, set your filters and date range, then click the download button in the top-right. The output is CSV. Analytics data can export to Looker, Tableau, Hex, and other business intelligence platforms.
• Analytics include total tickets, resolved count and resolution rate, open/in-progress breakdown, critical ticket count, mean and median response time, P95 response time, mean and median resolution time, weekly volume and resolved trend charts, response time trend by week, agent workload by tickets resolved, average resolution time per agent, priority breakdown, and channel mix.

What you cannot do from the UI:

• Bulk-export conversations, messages, or customers to CSV or JSON
• Export knowledge base articles in bulk
• Download attachments in bulk
• Export tag assignments or ticket type configurations

Plan-tier access differences:

Verify current tier requirements against Unthread's pricing page before committing to an export approach.

If your requirement is "get all my conversations out of Unthread," the API is the only path.

API-Based Export: Endpoints, Pagination, and Rate Limits

Authentication

In order to authenticate, you must send an HTTP header with the key "X-Api-Key" and the value set to the service account key created in the previous section. Service accounts are created under Setup > Service Accounts (project-scoped) or Workspace Settings > Service Accounts (tenant-wide). There are no limits on the number of service accounts you can create. Copy the key immediately — it is shown only once.

Key Endpoints for Full Export

POST /conversations/list          → All conversations (tickets)
POST /conversations/:id/messages/list → Messages per conversation
GET  /conversations/:id            → Single conversation detail
GET  /conversations/:id/files/:fileId/full → Download attachment
POST /customers/list               → All customers (channels)
POST /accounts/list                → All accounts (companies)
POST /users/list                   → All users (agents + external)
POST /tags/list                    → All tags
POST /ticket-types/list            → All ticket types + field defs
POST /knowledge-base/articles/list → All KB articles
POST /surveys/list                 → All surveys
POST /surveys/:id/responses/list   → Survey responses
GET  /outbounds                    → All outbound messages
GET  /webhook-subscriptions        → Webhook configs
POST /reporting/time-series        → Aggregated analytics
POST /user-groups/list             → User groups
GET  /conversations/:id/approval-requests → Approval requests

Pagination

Responses are paginated by providing a cursor to the next or previous page. The limit per page is 100. All list endpoints use POST with a standardized request body that accepts select, order, where, limit, descending, and cursor fields. The response includes a totalCount and a cursors object with hasNext, hasPrevious, next, and previous fields.

Documented where operators include ==, !=, >, <, in, notIn, contains, notContains, and like. Conversation status values are open, in_progress, on_hold, and closed. Priority values are 3 (urgent), 5 (high), 7 (normal), and 9 (low).

Error Handling and Known API Behaviors

The API documentation does not publish a comprehensive error code taxonomy. Based on standard REST conventions and the documented behavior:

When a cursor becomes invalid (e.g., due to data changes during extraction), the API may return a 400. If this happens mid-extraction, restart from the beginning of the current page using a fresh cursor from the previous successful response.

Rate Limits

Unthread's API documentation does not publish explicit per-minute or per-day rate limits as of mid-2026. This is a real gap for teams planning bulk extraction. In practice:

• Implement exponential backoff on HTTP 429 responses
• Start with a conservative 2 requests per second as a baseline and adjust based on observed 429 responses
• Monitor the Retry-After header if returned
• Handle HTTP 500+ responses with retry logic — transient server errors occur during large extractions
• Contact Unthread support (support@unthread.io) for guidance if extracting more than 50,000 records or if you need temporary rate limit increases

Extraction Script

// Node.js — Export all Unthread conversations with retry + cursor pagination
const API_BASE = 'https://api.unthread.io/api';
const API_KEY = process.env.UNTHREAD_API_KEY;
const DELAY_MS = 500; // Baseline: 2 req/sec — increase if no 429s observed
const MAX_RETRIES = 5;
const CONCURRENCY = 1; // Single-threaded by default; see concurrency notes below
 
async function fetchWithRetry(path, options = {}, attempt = 0) {
  if (attempt >= MAX_RETRIES) {
    throw new Error(`Max retries (${MAX_RETRIES}) exceeded for ${path}`);
  }
 
  const res = await fetch(`${API_BASE}${path}`, {
    ...options,
    headers: {
      'X-Api-Key': API_KEY,
      'Content-Type': 'application/json',
      ...(options.headers || {})
    }
  });
 
  if (res.status === 429 || res.status >= 500) {
    const retryAfter = parseInt(res.headers.get('Retry-After') || '0', 10);
    const delayMs = retryAfter
      ? retryAfter * 1000
      : Math.min(30000, 1000 * 2 ** attempt);
    console.warn(`${res.status} on ${path}. Retry ${attempt + 1}/${MAX_RETRIES} in ${delayMs}ms...`);
    await sleep(delayMs);
    return fetchWithRetry(path, options, attempt + 1);
  }
 
  if (res.status === 400) {
    const body = await res.text();
    console.error(`400 Bad Request on ${path}: ${body}`);
    throw new Error(`Bad request: ${body}`);
  }
 
  if (!res.ok) throw new Error(`API error: ${res.status} on ${path}`);
  return res.json();
}
 
async function fetchAllConversations() {
  const allConversations = [];
  let cursor = null;
  let hasNext = true;
  let page = 0;
 
  while (hasNext) {
    const body = {
      select: [
        'id', 'friendlyId', 'title', 'status', 'priority',
        'createdAt', 'updatedAt', 'closedAt',
        'assignedToUserId', 'customerId', 'channelId',
        'responseTime', 'responseTimeWorking',
        'resolutionTime', 'resolutionTimeWorking',
        'tags.id', 'tags.name',
        'ticketTypeId', 'ticketTypeFields',
        'summary', 'files', 'metadata'
      ],
      order: ['createdAt', 'id'],
      limit: 100,
      descending: false,
      ...(cursor ? { cursor } : {})
    };
 
    const json = await fetchWithRetry('/conversations/list', {
      method: 'POST',
      body: JSON.stringify(body)
    });
 
    allConversations.push(...json.data);
    hasNext = json.cursors.hasNext;
    cursor = json.cursors.next;
    page++;
 
    console.log(
      `Page ${page}: ${json.data.length} records ` +
      `(total: ${allConversations.length}/${json.totalCount})`
    );
    await sleep(DELAY_MS);
  }
 
  return allConversations;
}
 
async function exportWorkspace() {
  // Phase 1: Export reference data (needed for ID resolution)
  const [users, customers, accounts, tags, ticketTypes] = await Promise.all([
    fetchAllPages('/users/list', { includeExternalUsers: true }),
    fetchAllPages('/customers/list'),
    fetchAllPages('/accounts/list'),
    fetchAllPages('/tags/list'),
    fetchAllPages('/ticket-types/list')
  ]);
 
  // Phase 2: Export conversations
  const conversations = await fetchAllConversations();
 
  // Phase 3: Fetch messages + attachments per conversation
  for (const convo of conversations) {
    const msgs = await fetchAllPages(
      `/conversations/${convo.id}/messages/list`
    );
    convo._messages = msgs;
 
    // Download file attachments
    if (Array.isArray(convo.files)) {
      for (const file of convo.files) {
        try {
          const fileRes = await fetch(
            `${API_BASE}/conversations/${convo.id}/files/${file.id}/full`,
            { headers: { 'X-Api-Key': API_KEY } }
          );
          // Stream fileRes.body to disk or object storage
        } catch (err) {
          console.error(`Failed to download file ${file.id}: ${err.message}`);
        }
      }
    }
 
    await sleep(DELAY_MS);
  }
 
  // Phase 4: Write everything to your archive format
  return { conversations, users, customers, accounts, tags, ticketTypes };
}
 
// Generic paginator for any list endpoint
async function fetchAllPages(path, extraBody = {}) {
  const all = [];
  let cursor = null;
  let hasNext = true;
  while (hasNext) {
    const json = await fetchWithRetry(path, {
      method: 'POST',
      body: JSON.stringify({ limit: 100, ...extraBody, ...(cursor ? { cursor } : {}) })
    });
    all.push(...json.data);
    hasNext = json.cursors?.hasNext ?? false;
    cursor = json.cursors?.next ?? null;
    await sleep(DELAY_MS);
  }
  return all;
}
 
function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

Concurrency Strategies for Large Exports

The script above is single-threaded. For datasets over 50,000 conversations, consider these approaches:

• Parallel message fetching: After retrieving all conversation IDs, split them into batches and fetch messages with a concurrency pool (e.g., p-limit with concurrency of 3–5). Monitor for 429s and reduce concurrency dynamically.
• Separate attachment workers: File downloads are I/O-bound and can run in parallel via a worker queue. Use a separate rate-limited pool for GET /files/:id/full calls.
• Checkpoint-based resumption: Write cursor state and completed conversation IDs to disk after each page. If the script crashes, resume from the last checkpoint rather than restarting.

At concurrency 5 with no throttling, message extraction for 10,000 conversations drops from ~90 minutes (single-threaded at 2 req/sec) to ~18 minutes. Adjust based on observed 429 frequency.

Throughput Math

At 100 records per page and a conservative 2 requests per second (single-threaded):

• 1,000 conversations: ~10 pages → under 10 seconds (conversation metadata only)
• 10,000 conversations: ~100 pages → under 2 minutes (conversation metadata only)
• 100,000 conversations: ~1,000 pages → under 10 minutes (conversation metadata only)

The bottleneck is message extraction. Each conversation requires a separate POST /conversations/:id/messages/list call. For 10,000 conversations averaging 8 messages each, that adds roughly 10,000 additional API calls — approximately 83 minutes at 2 requests per second (single-threaded). Attachments add another pass: 10,000 conversations × 1.5 average attachments = ~15,000 file downloads, adding approximately 125 minutes at 2 req/sec.

Total extraction time for 10,000 conversations with messages and attachments (single-threaded, 2 req/sec): approximately 3.5 hours. With concurrency 5: approximately 45 minutes.

Exporting Attachments, Files, and Media

Unthread stores file metadata on the conversation object in the files array. Each entry includes id, name, size, filetype, and mimetype. The actual file content must be downloaded separately.

Download endpoint:

GET /conversations/:conversationId/files/:fileId/full

Constraints:

• Maximum file size: 20MB per file
• Slack enforces 10 file attachments per message (not per conversation)
• Downloads are one file per request — there is no bulk zip download
• Inline images posted in Slack threads are captured if they were posted as file attachments; paste-in screenshots may only be available via Slack's own API
• Unthread does not publish a separate file manifest endpoint — build your own as you crawl conversations

[For engineering] If you have 5,000 conversations with an average of 1.5 attachments each, that's ~7,500 individual download requests. At 2 requests per second (single-threaded), that's roughly 62 minutes of download time before accounting for file transfer bandwidth. With concurrency 5 and no throttling: approximately 12 minutes. Plan storage accordingly — at an average of 500KB per file, 7,500 files ≈ 3.7GB.

What Data Cannot Be Exported from Unthread?

Two data gaps that exist before Unthread even sees the data:

• Slack channel backfill is limited to 6 months when connecting a channel. Older history never enters Unthread.
• Email support only creates tickets for new emails received after setup, not past mailbox history.

If you rely on Unthread as your system of record, export legacy Slack and email history from the source systems separately.

Data Format, Encoding, and Cleanup After Export

The Unthread API follows RESTful conventions when possible, with most operations performed via GET, POST, PATCH, and DELETE requests. Request and response bodies are encoded as JSON.

All API responses are JSON (UTF-8). There is no native CSV or XML export from the API. The dashboard exports analytics as CSV — test a sample for UTF-8 BOM behavior before hard-coding a downstream loader.

Common post-export issues:

• Nested objects: Tags, custom field values, followers, and collaborators are nested arrays on conversation records. Flattening them for CSV or import into a destination platform requires explicit mapping logic. For example, tags must be either pipe-delimited into a single column or exploded into separate rows.
• Timestamps: createdAt, updatedAt, closedAt are ISO 8601 strings (e.g., "2025-11-14T09:23:41.000Z"). Slack message timestamps use Unix epoch format (e.g., "1675183719.124879"). Normalize before import.
• Slack mrkdwn in messages: Message text fields contain Slack mrkdwn formatting, including user mentions like <@U012AB3CD>. If migrating to a platform that expects HTML or plain text, you need a conversion step. Those <@U...> references must be cross-referenced against your Slack workspace directory (via Slack's users.info API) to resolve to actual names or email addresses — otherwise they render as broken text in the destination.
• Custom field key mapping: Conversation custom values live in ticketTypeFields keyed by field UUID (e.g., "fld_abc123-def456": "Production"), not by human-readable label. You must export ticket type definitions from POST /ticket-types/list and build a UUID → label lookup table.
• Orphaned references: Conversations may reference a customerId or assignedToUserId that was deleted. Validate referential integrity post-export by checking all foreign key references against your exported user and customer datasets.
• Dual IDs: Preserve both the UUID-style id (e.g., conv_a1b2c3d4...) and the human-friendly friendlyId (e.g., TKT-1042) on conversations — you'll need both during migration and for user-facing audit trails.
• Duplicate tag names: Tags are identified by UUID, but name collisions are possible if tags were renamed over time. Deduplicate by UUID, not by name.

Post-export validation checklist:

1. Total conversation count in export matches totalCount from the first API response
2. Every conversation has at least one message (fetch count from messages endpoint)
3. All customerId references resolve to a record in your exported customers dataset
4. All assignedToUserId references resolve to a record in your exported users dataset
5. File attachment metadata count matches successfully downloaded file count
6. Date ranges in export match expected historical range (check createdAt min/max)
7. Ticket type field values are present (not null) for conversations with a ticketTypeId
8. Tag associations survive the flattening process — spot-check 10 conversations manually

Export for Migration vs. Backup vs. Compliance

Define your objective before writing extraction code. The scope changes significantly based on use case.

Migration

The goal is reshaping Unthread data for import into a destination platform (Zendesk, Freshdesk, Intercom, Jira Service Management, etc.). Key considerations:

• ID mapping: Unthread uses UUIDs for all objects. Your destination will assign its own IDs. Build and maintain a mapping table (unthread_id → destination_id) for every object type. Persist this mapping — you will need it for post-migration validation and for resolving cross-references.
• Relationship preservation: Conversation-to-customer, conversation-to-assignee, and conversation-to-tag relationships must be reconstructed using the mapping table.
• Message threading: Unthread stores messages per conversation, which maps well to most destination platforms' per-ticket threading — but message author attribution requires matching Unthread user IDs to destination user IDs.
• Custom fields: Unthread's ticketTypeFields are key-value pairs keyed by field UUID. Map each UUID to the corresponding field in the destination. Field type compatibility matters: Unthread's multi-user-select may not have a direct equivalent in every platform.
• Automations rebuild: Plan to manually recreate routing rules, escalation workflows, and auto-response configurations. These cannot be exported.
• Destination API constraints: Each target platform imposes its own import limits. Zendesk's Ticket Import API caps at 100 tickets per request. Freshdesk's import API requires tickets to reference existing contacts. Jira Service Management uses a different threading model (comments, not messages). Plan your transformation layer around the destination's constraints, not just the source's structure.

For related migration guides, see Kustomer to Unthread Migration and How to Migrate Multiple Help Desks Into One.

Backup

For a full-fidelity backup, you need: all conversations with message histories, customer and account records, file attachments (downloaded as binary), tag definitions and assignments, ticket type definitions and field values, knowledge base articles, survey data, and user records.

Since there is no native scheduled export, you'll need a cron job or orchestration tool (GitHub Actions, AWS Lambda, Cloud Scheduler) running the extraction script on a recurring basis.

For incremental backup after the initial backfill, Unthread documents webhook events for conversation_created, conversation_updated, conversation_deleted, and message_created. Your webhook receiver must answer URL verification within 3 seconds and regular events within 30 seconds. Unthread retries failed deliveries up to 4 more times and eventually disables an endpoint after more than 100 consecutive failures or a 410 response.

Compliance (GDPR, DSAR)

Unthread's API supports filtering conversations by customerId, enabling per-individual data extraction for DSAR fulfillment. There is no pre-built DSAR workflow in the UI. You will need to:

1. Identify the customer record by email or Slack ID using POST /customers/list with a where filter
2. Extract all conversations linked to that customerId
3. Extract all messages within those conversations
4. Download associated file attachments
5. Package the data in a machine-readable format (JSON is native; CSV requires transformation)
6. Document the extraction process for your compliance audit trail

Data is always encrypted in transit and at rest, and is retained until a deletion request is made. Deletion requests can be made by emailing security@unthread.io.

Unthread is SOC 2 Type II compliant and HIPAA compliant with BAA for enterprise plans.

This compliance posture supports data export workflows but does not substitute for your own chain-of-custody documentation. For a deeper dive on compliance during migration, see our GDPR Compliant Data Migration guide.

Vendor Lock-In and Data Portability Assessment

Unthread scores well on data portability for a Slack-native helpdesk. The core data model is well-structured and fully API-accessible. The lock-in risk concentrates in configuration and workflow state, not in operational data.

[For CTOs] The real switching cost is not data extraction — it's automation and workflow reconstruction. If you've built 20+ automations with conditional branching, escalation steps, and AI response rules, plan 2–4 weeks of rebuilding effort in the target platform. The data itself moves in days. The portability gap is entirely in configuration state, not in operational data.

Unthread's terms of service do not impose restrictions on data export or portability. Data is retained until a deletion request is made, per the terms at unthread.io/terms. There are no documented API call quotas tied to plan tiers that would block a full export.

Decision Matrix: Which Export Method to Use

Timeline and Resourcing for a Full Data Export

These estimates assume a single developer working on a standard workstation with stable network connectivity, running the extraction script single-threaded at 2 requests per second. Parallelism reduces extraction time proportionally (see concurrency section above).

[For PMs] If you only need conversation metadata (no message bodies, no files), cut extraction time by 60–80%. The validation phase is where most projects slip — budget accordingly. Common validation failures: orphaned customer references, missing messages on older conversations, and custom field values that don't match current ticket type definitions (indicating the ticket type was modified after the conversation was created).

Minimum team composition:

• API export: 1 developer with Node.js or Python experience and API integration skills
• Data transformation: Same developer, or a data engineer if the target schema is complex (e.g., migrating to a platform with a fundamentally different threading model)
• Validation: PM + 1 CS team member to spot-check record accuracy against the Unthread UI