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

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

Exporting data from Deskpro requires understanding the platform's dual-deployment nature. Deskpro runs as both a Cloud SaaS product and a self-hosted On-Premise solution, and your extraction strategy depends entirely on where your instance lives. Cloud users are limited to UI exports and the REST API. On-Premise users can bypass the API entirely with direct database access.

Whether you are archiving records, feeding an external data warehouse, or preparing for a platform migration, treating a helpdesk export as a simple CSV download will result in orphaned data. This guide covers the exact methods, API constraints, schema structure, and trade-offs for getting your data out of Deskpro completely and correctly.

Which Deskpro Export Path Should You Use?

• UI CSV export — Best for quick ticket-list downloads and filtered queue snapshots. Exports ticket ID, subject, requester name, email, and custom fields. Does not export message bodies or attachments. (support.deskpro.com)
• Stat Builder / DPQL — Best for structured slices, audits, and one-off reporting. DPQL is a SQL-like query language that joins Deskpro's internal tables and exports results as CSV. Caps at approximately 2,500 rows and 55 fields per query; fails silently above those thresholds. (support.deskpro.com)
• REST API v2 — Best for migrations, sync jobs, and full-fidelity extraction. Supports sideloading, pagination, batch requests, and date-pinned version paths. Required for Cloud users doing any non-trivial extraction. (github.com)
• Database dump (On-Premise only) — Best for whole-instance extraction. Deskpro documents both dputils backup and manual MySQL dump plus attachment archive workflows. No rate limits; files and database must be exported separately. (support.deskpro.com)

What Data Can You Export from Deskpro?

Deskpro's data model is relational, built around Tickets, Messages (replies and notes), People (users and agents), Organizations, and Blobs (attachments). The fidelity of your export depends on the method you choose.

Deskpro's DPQL table reference includes additional tables: articles, article_attachments, downloads, chat_messages, news, tickets_logs, and ticket_attachments. (support.deskpro.com)

Deskpro's Core MySQL Schema (On-Premise Reference)

For On-Premise users working from a database dump, the key tables and their relationships are:

The custom_data_ticket table stores all custom field values as rows, not columns — meaning a ticket with 10 custom fields has 10 rows in this table. ETL pipelines must pivot this structure before loading into most target systems.

Attachments are stored on the filesystem, not as BLOBs in the database. The blobs table contains metadata (filename, MIME type, size, storage path) but not the file binary. Always export the attachment directory alongside the SQL dump. (support.deskpro.com)

Method 1: CSV Exports and DPQL

For non-technical users or ad-hoc reporting, Deskpro provides two UI-based export methods: the standard list view export and custom reports using DPQL.

List View CSV Export

Agents can navigate to any ticket, person, or organization list, apply filters, and export as CSV or Excel. This is the fastest way to extract flat data.

Trade-offs:

• No relational data. You get a flat file. A ticket export shows the assigned agent ID and user ID, but not their full profiles.
• No message bodies. The export includes ticket subject and custom fields, but drops conversation history.
• Scale limits. Deskpro's own ticket-report guidance tops out at about 2,500 tickets per query. Large exports may time out or require batching by ID range. (support.deskpro.com)

Treat the UI CSV as a list export, not a conversation archive.

Deskpro Query Language (DPQL)

DPQL is a SQL-like syntax for querying Deskpro's underlying data structure. You can join tables and export results as CSV.

Tickets with user emails:

SELECT tickets.id, tickets.subject, tickets.person.primary_email.email, tickets.date_created 
FROM tickets 
WHERE tickets.status = 'resolved'

People with organization names:

SELECT people_emails.person.id,
       people_emails.person,
       people_emails.email,
       people_emails.person.organization.name AS 'Organization Name'
FROM people_emails
ORDER BY people_emails.person.id;

To include message content, use the cross-referencing pattern tickets.messages.message with GROUP BY tickets.id to collapse multiple messages per ticket into one row:

SELECT tickets.date_created,
       tickets.subject,
       tickets.messages.message,
       tickets.department
FROM tickets
WHERE tickets.date_created = %LAST_WEEK%
GROUP BY tickets.id;

Where DPQL falls short:

• Report queries start failing at around 55 fields. (support.deskpro.com)
• It truncates long text fields and strips HTML from message bodies.
• It cannot export binary attachments.
• It tops out at about 2,500 tickets per query, requiring ID-range batching for larger datasets.
• Checkbox, date, and multi-select custom fields require special handling. Checkbox fields return 0/1 rather than boolean labels. Multi-select fields return pipe-delimited (|) or comma-delimited strings rather than arrays, which requires splitting during transformation.

If you are migrating to a new platform, relying on DPQL CSVs will result in data loss. Use DPQL for sampling and field mapping validation, not as your production extraction method.

Method 2: Deskpro REST API v2 (The Migration Route)

For Deskpro Cloud users migrating to another platform, the REST API v2 is the only viable path for full data portability. The API is capable, but it requires handling specific quirks: sideloading, pagination, blob extraction, and a critical default status filter.

Authentication, Versioning, and Permissions

Generate an API key in Admin > Apps & Integrations > API Keys. The key is passed in the Authorization header:

curl -H "Accept: application/json" \
     -H "Authorization: key YOUR_API_KEY" \
     "https://yourdomain.deskpro.com/api/v2/tickets?page=1&count=100&include=person,department"

Deskpro supports date-pinned version paths like /api/v2/YYYYMMDD/ to lock your scripts against a specific API version. Use your instance's /api/v2/doc browser as the source of truth for available endpoints — Deskpro's public support center mixes documentation from different API generations, and endpoint availability varies by On-Premise release version. (github.com)

The Inactive Ticket Trap

This is the single most common Deskpro export mistake.

To capture the full ticket corpus, your API requests must explicitly enumerate all status values:

GET /api/v2/tickets?status=live,awaiting_agent,awaiting_user,pending,resolved,archived,hidden

Run a DPQL count query per status before your API extraction begins. Compare the DPQL totals against your API response meta.total field after extraction completes. Any delta indicates scope gaps. This reconciliation step catches the inactive ticket problem before it becomes a migration defect.

Pagination and Rate Limiting

Deskpro API v2 uses page and count parameters for pagination. The response metadata includes meta.total, meta.page, and meta.pages for iteration control.

Deskpro does not publish a single universal requests-per-minute number in its public API docs. It documents per-key hourly and daily limits, a cloud-wide abuse-prevention limit, and HTTP 429 responses when limits are crossed. In practice, aggressive extraction scripts without backoff will trigger throttling; spacing requests at 200–500ms intervals is a conservative baseline for Cloud instances. Build retry logic with exponential backoff starting at 1 second, doubling up to a 60-second cap, and checkpoint completed page ranges to disk so that interrupted jobs resume rather than restart. (github.com)

API error response semantics:

• HTTP 429 — Rate limit exceeded. Back off and retry.
• HTTP 403 — Insufficient permissions for the requested resource. The API key user lacks access to that department, ticket, or private note. (support.deskpro.com)
• HTTP 404 — The resource does not exist at that ID, or has been permanently deleted (distinct from archived/hidden). Do not treat 404 as a fatal error during bulk extraction — log and skip.
• HTTP 500 — Server-side error, often triggered by malformed include parameters or oversized batch requests. Reduce payload complexity and retry.

Sideloading Related Objects

One of the API's best features is sideloading. Instead of making separate calls to fetch the user profile for every ticket, request related objects in a single call using the include parameter:

GET /api/v2/tickets?include=person,assigned_agent,organization

The JSON response includes a linked object alongside the data array, containing full profiles of requested entities, deduplicated by ID.

Sideloading prevents API exhaustion. Consider a Deskpro instance with 100,000 tickets. Without sideloading, fetching each user profile separately means 100,001 API calls — at 200ms spacing, that is roughly 5.5 hours of sequential HTTP requests for user data alone. With ?include=person, your script builds a local dictionary from the linked.person objects and maps them in memory — reducing that 5.5 hours to zero additional calls. Supported sideload entities include person, assigned_agent, assigned_team, organization, and department.

For multi-object export jobs, Deskpro's /batch endpoint groups several lookups into a single request, further reducing round trips. (github.com)

Extracting Conversation Threads

Tickets do not contain conversation history in their primary payload. To extract replies and internal notes, iterate through every ticket ID:

GET /api/v2/tickets/{ticket_id}/messages

This returns the message body (HTML), date_created, and the authoring person.

Critical mapping detail: Deskpro differentiates between public replies and internal notes using the is_note boolean field. If your migration script ignores this flag, you risk exposing internal agent notes to customers in the target system. Always map is_note: true to the target platform's equivalent of a private/internal note, and validate this mapping before cutover with a manual spot-check of a sample ticket that contains both public replies and internal notes.

At 100 tickets per page, extracting messages for 100,000 tickets requires 1,000 paginated ticket-list requests plus up to 100,000 individual message requests. Parallelizing message extraction with a worker pool (10–20 concurrent connections is a reasonable ceiling before throttling risk increases) reduces this from days to hours on Cloud instances.

Handling Custom Fields

Custom fields are not returned as simple key-value pairs at the ticket root. They are nested within a custom_fields object, and different field types serialize differently:

• Dropdown fields return integer IDs, not human-readable values. A 'Product Tier' dropdown might return 14 instead of "Enterprise".
• Checkbox fields return true/false booleans.
• Date fields return ISO 8601 strings (YYYY-MM-DD), but the target system may expect Unix timestamps or a different format.
• Multi-select fields return arrays of integers, each mapping to a choice definition in the field schema.
• Text and textarea fields return raw strings; long textarea values may contain HTML if the agent used a rich text editor.

To resolve IDs to human-readable values:

1. Fetch the field schema. Query /api/v2/ticket_fields to get the master list of custom fields and their choice mappings. Cache this response — it does not change during an extraction run.
2. Map during transformation. Cross-reference each ticket's custom_fields IDs against the schema to extract readable values before loading into the target system.
3. Handle null values explicitly. Fields that were never filled return null, not an empty string. Some target import APIs reject null values; your transform layer should convert them to empty strings or omit them entirely based on the target schema's requirements.

Webhooks for Incremental Extraction

Deskpro supports outbound webhooks that fire on ticket events (creation, update, status change, new message). For ongoing sync scenarios — feeding a data warehouse or keeping a secondary system current — webhooks are more efficient than polling the API.

Webhook payloads contain the ticket ID and event type but not the full ticket record. Your webhook consumer must call the API to fetch the updated record after receiving the event. This two-step pattern (receive event → fetch record) is standard for Deskpro integrations. Webhooks do not backfill historical data; they only capture events from the point of configuration forward.

Exporting Guides and Knowledge Base Content

Deskpro uses different terminology in its API: guide pages are called topics. To export guide content, you need multiple endpoints:

• GET /api/v2/guides/{id} — guide metadata (title, slug, visibility)
• GET /api/v2/topics?guide={id} — all topic content for that guide (HTML body, title, parent_id)
• GET /api/v2/guides/{id}/tree — hierarchy and navigation structure

There is no single endpoint that returns metadata, content, and tree in one response. Skip the tree endpoint and your guide exports will lose their navigation structure — pages will exist in the target system but with no parent-child relationships, effectively flattening a multi-level guide hierarchy into an unordered list. (support.deskpro.com)

For knowledge base articles, /api/v2/articles returns article HTML. Validate the exact available operations in your instance's /api/v2/doc browser before scripting against them. (support.deskpro.com)

Method 3: Direct Database Dump (On-Premise Only)

If you host Deskpro On-Premise, you can bypass the API entirely. Deskpro runs on MySQL/MariaDB, and a direct dump is the fastest way to extract 100% of your data.

mysqldump -u root -p deskpro_database > deskpro_export.sql

Deskpro also documents a dputils backup command for managed private-controller deployments. (support.deskpro.com)

Why a DB dump wins:

• Zero rate limits. Extract gigabytes in seconds.
• Perfect fidelity. Every relational link, custom field, and historical log.
• No pagination logic. No iterative scripts to page through millions of messages.

The normalization trade-off: The raw schema is highly normalized. Custom field values are stored in a separate custom_data_ticket table as EAV (Entity-Attribute-Value) rows — one row per field per ticket — rather than columns. A ticket with 20 custom fields generates 20 rows in custom_data_ticket. Migrating to any SaaS platform requires an ETL pipeline to pivot this structure, resolve field IDs to names, join messages, and push via the target's import API. The dump saves extraction time but does not eliminate transformation complexity.

Do not forget attachments. Deskpro's private-export documentation explicitly separates the database dump from the attachment directory archive. Files live on the filesystem under a configured storage path, not in the database. The blobs table contains the filename, MIME type, and relative storage path; the actual binary files must be archived separately. Export both and verify the storage path in your Deskpro admin config before running the backup. (support.deskpro.com)

Handling Attachments and Blobs

Attachments are the most common point of failure in any helpdesk migration. Deskpro stores files using a Blob architecture — each uploaded file gets a unique Blob ID that is referenced by messages and tickets.

In the API, messages contain an attachments array listing Blob IDs. To export:

1. Parse the attachments array in the message payload.
2. Extract each Blob ID.
3. GET /api/v2/blobs/{blob_id}/download to retrieve the binary file.
4. Save the stream to local or cloud storage.
5. Log the new file URL for mapping into the target helpdesk.

Scale consideration: At 100,000 attachments averaging 200KB each, sequential single-threaded downloading produces roughly 20GB of data. At a sustained 10MB/s download rate, that is approximately 33 minutes. In practice, Cloud API rate limits and network latency will extend this to several hours with single-threaded sequential requests. Decouple data extraction from file downloading using asynchronous workers and 10–20 parallel download jobs. Log each blob ID and its download status to a checkpoint file so failed downloads can be retried without re-extracting the full ticket corpus.

The Inline Image Trap

Attachments at the bottom of an email are easy to spot. Inline images — pasted directly into the message body — are harder. Deskpro stores inline images as HTML <img> tags pointing to Blob download URLs embedded in the message HTML.

If you push the raw HTML body to a new helpdesk, those image links will break the moment your Deskpro instance is decommissioned. Your extraction script must:

1. Parse the HTML body of each message.
2. Identify deskpro.com/api/v2/blobs/ URLs in <img src="..."> attributes.
3. Download each image using the blob download endpoint.
4. Upload it to the new system's media storage.
5. Rewrite the src attributes in the HTML before loading.

This rewriting step is frequently omitted from migration scripts, producing tickets that render correctly during testing (while Deskpro is still live) and break silently after cutover.

Deskpro Export Failure Modes

Before initiating any export, plan for these known failure patterns:

• Inactive tickets silently missing because the export never requested resolved, archived, or hidden statuses. Validate by comparing DPQL status counts against API meta.total per status. (support.deskpro.com)
• 403 errors or partial data because the API key is tied to the wrong agent, is missing department access, or is blocked by tag-based permission restrictions. (support.deskpro.com)
• Reports that look complete but aren't because you hit the ~55-field ceiling or stayed inside list/report output instead of extracting thread-level data. (support.deskpro.com)
• Guide exports with missing structure because you pulled topics but skipped the guide tree endpoint, flattening navigation hierarchy. (support.deskpro.com)
• Attachment gaps because files were not exported separately from record payloads, or blob download errors were not logged and retried.
• Inline image breakage because raw HTML message bodies were migrated without rewriting blob URLs.
• Internal notes exposed as public replies because is_note: true messages were not mapped to the target platform's private note equivalent.
• Custom field data loss because dropdown, multi-select, or date fields were not resolved against the field schema before transformation.
• Password hashes cannot be exported or migrated in usable form. Deskpro uses bcrypt or equivalent one-way hashing; users must trigger password resets on the new platform.
• SLA metrics are difficult to reconstruct. You can calculate resolution times from ticket timestamps, but SLA timer state, pause events, and breach records are buried in tickets_logs and rarely surfaced cleanly through API v2. Extract tickets_logs explicitly if SLA history is a compliance requirement.

Export Preparation Checklist

Before writing extraction code or clicking download:

1. Define scope explicitly. Decide whether you need active tickets only, or also resolved, archived, hidden, spam, and deleted history. Deskpro's defaults will not make this decision for you. Run DPQL counts by status to establish baseline totals. (support.deskpro.com)
2. Validate permissions before volume. Bind the API key to an admin-capable user. Test against a single known ticket in each department before running the full extraction.
3. Use DPQL for sampling. Prototype filters and confirm field mappings in Stat Builder before automating the full run. Verify row counts against expected totals.
4. Purge spam and noise. Create a DPQL query to identify tickets from known spam domains or mailer-daemon addresses. Bulk delete them — every gigabyte of junk removed saves extraction, storage, and transformation time.
5. Audit custom fields. Over time, helpdesks accumulate redundant fields. Document every active field, its type (text, dropdown, checkbox, date, multi-select), and its target destination. Fetch /api/v2/ticket_fields and cache the schema before extraction begins.
6. Split content types deliberately. Tickets, people, organizations, articles, guides/topics, logs, and attachments should each have their own extraction pipeline, checkpoint file, and validation step.
7. Reconcile counts before cutover. Compare record totals by status, date range, and object type across DPQL reports, API meta.total fields, and target import confirmation logs. Any unexplained delta requires investigation before go-live.
8. Archive the raw export. Keep the original JSON, CSV, and file archive even after migration succeeds. Audit requests and edge-case investigations routinely surface weeks after cutover.

How Deskpro Compares to Zendesk and Freshdesk for Exports

Deskpro, Zendesk, and Freshdesk take meaningfully different approaches to data portability. This comparison reflects our reading of each vendor's public API documentation, not official vendor positions.

The practical implication: Zendesk's incremental export endpoint is purpose-built for extraction at scale, with cursor-based pagination that survives interruption and restarts. Deskpro requires you to build that resumability yourself using page checkpoints. Freshdesk's low default page size (30 records) makes naive extraction scripts 3× slower than Deskpro's 100-record default without tuning. Deskpro's unique advantage is direct database access for On-Premise deployments — neither Zendesk nor Freshdesk offer equivalent access.

Mapping Deskpro Data to Other Platforms

Extracting the data is the first half. Transforming Deskpro's schema into the target platform's data model is the second.

Deskpro to Jira Service Management: JSM operates on Issue Types and Request Types — a fundamentally different architecture from Deskpro's flat ticket model. Deskpro 'Departments' map to JSM 'Projects', and Deskpro 'Categories' map to JSM 'Request Types'. Custom field types require explicit mapping: Deskpro dropdown fields become JSM Select List fields; Deskpro multi-select fields become JSM Multi-select fields. See our Deskpro to Jira Service Management Migration Technical Guide.

Deskpro to Zoho Desk: Zoho Desk enforces a strict Department structure. If you run a single-department Deskpro setup but want Zoho's multi-department features, you need transformation logic to route tickets based on tags or custom fields. Zoho's import API enforces field type matching more strictly than Deskpro's flexible schema. See our Deskpro to Zoho Desk Migration Guide.

Deskpro to Help Scout: Help Scout uses Mailboxes and Conversations with a threading model that separates customer-visible replies from internal notes at the data level — making Deskpro's is_note boolean a direct mapping target. Custom field mapping requires translating Deskpro's field types to Help Scout's Custom Fields schema, which supports fewer field types than Deskpro. See our Deskpro to Help Scout Migration Guide.

The Practical Takeaway

Deskpro is exportable. The hard part is not getting data out — it is getting it out with enough fidelity to rebuild elsewhere.

For quick visible lists, the UI CSV works. For reporting slices, DPQL is faster than code. For migration, compliance, warehouse loading, or platform replacement, the API is the right tool — and you must treat statuses, permissions, help-center structure, custom field types, and attachments as first-class concerns from the start.

The breakpoints are predictable and consistent: inactive tickets get missed because of the default status filter; API keys are under-scoped because they were created by a non-admin; help-center content gets flattened because the guide tree endpoint was skipped; custom field values arrive as unresolved integers; and attachments get handled last instead of first. A single missed is_note boolean turns private agent notes into public customer replies. Inline image URLs break silently after cutover rather than loudly during testing.

Plan for all of these before your first API call, not after your first production incident.