Asynchronous message statistics export

exportMessagesStatistics exports message history and statistics to a CSV file on the server. Use it for large or full-account pulls that messages:list can’t handle.

When to use export instead of messages:list

Use messages:list for live, paginated lookups of a bounded period. Use exportMessagesStatistics when the result would exceed the deep-pagination limit of messages:list (page × per_page > 100000), or when the goal is a single downloadable file rather than paged JSON. The export has no limit on date_range or row count, because it streams the result to a file on disk instead of holding it in one response.

How the export flow works

1. Call export with the same filters as messages:list. The response returns a uid task identifier immediately, before the file is generated.
2. Poll status with that uid until it reports STATUS_SUCCESS (or STATUS_FAILED).
3. Call result with the same uid to get the generated file and a ready-to-use file_url.
4. Download the file. Use file_url as-is, or see result for building the URL from file if it came back empty.

Use lastTasks to look up recent export tasks for an application, and delete to cancel a task or remove its file early.

Methods

The export lifecycle has five methods, plus a plain download endpoint:

Method	Description
exportMessagesStatistics/export	Queues an export and returns a task uid.
exportMessagesStatistics/status	Checks task progress.
exportMessagesStatistics/result	Returns the generated file name once the task is done.
exportMessagesStatistics/lastTasks	Lists recent export tasks for an application.
exportMessagesStatistics/delete	Cancels a task or removes its file before the retention window expires.
Download	Downloads the generated CSV file by name.

export

Queues a message history export and returns a task identifier right away.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/export

Headers

The request needs a Server API token:

Name	Required	Description
Authorization	Yes	Server API token. Must be provided in the following format: Authorization: Api <Server Key>.

Request body parameters

The request body accepts the following fields:

Name	Required	Type	Description
type	Yes	String	Must be “TASK_TYPE_EXPORT_MESSAGES_V2”.
export_messages_v2	Yes	Object	Export parameters, described below.
export_messages_v2.application_code	See note	String	Pushwoosh application code. Required if app_group_code is not set.
export_messages_v2.app_group_code	See note	String	Application group code, exports across every app in the group. Required if application_code is not set.
export_messages_v2.search	No	String	Free-text search over message title and content.
export_messages_v2.filters	No	Object	Message filters, described below. Omit to export the whole account history.
export_messages_v2.properties	No	Array	Columns to include in the CSV, described below.

export_messages_v2.filters accepts:

Name	Type	Description
statuses	Array	Message statuses to include. Possible values ”MESSAGE_STATUS_CANCELED" "MESSAGE_STATUS_CREATING" "MESSAGE_STATUS_DONE" "MESSAGE_STATUS_FAIL" "MESSAGE_STATUS_PENDING" "MESSAGE_STATUS_PROCESSING" "MESSAGE_STATUS_WAITING”
platforms	Array	Platform codes (numeric, e.g. 1 for iOS), not the platform name strings used by messages:list.
sent_date	Object	Reporting period filtered on send date: {"date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD"}.
created_date	Object	Reporting period filtered on message creation date, same format as sent_date.
created_via	Array	Message source. Possible values ”AB_TEST" "API" "AUTO_PUSH" "CP" "CSV" "CUSTOMER_JOURNEY" "EMAIL_API" "EMAIL_CP" "GEO_ZONE" "PUSH_ON_EVENT" "RSS" "SYSTEM”
segments	Array	Filter codes the message was sent to.
campaigns	Array	Campaign codes. Unlike messages:list, this takes a list, not a single code.
message_id	String (uint64)	A single numeric message ID, quoted. Unlike messages:list, export takes one ID, not an array.
message_code	String	A single message code.

export_messages_v2.properties selects which columns the CSV contains.

Possible values

• "EXPORT_MESSAGE_PROPERTY_ID"
• "EXPORT_MESSAGE_PROPERTY_TIMESTAMP"
• "EXPORT_MESSAGE_PROPERTY_CONTENT"
• "EXPORT_MESSAGE_PROPERTY_TITLE"
• "EXPORT_MESSAGE_PROPERTY_APPLICATIONS"
• "EXPORT_MESSAGE_PROPERTY_STATUS"
• "EXPORT_MESSAGE_PROPERTY_PLATFORMS"
• "EXPORT_MESSAGE_PROPERTY_SOURCE"
• "EXPORT_MESSAGE_PROPERTY_FILTER"
• "EXPORT_MESSAGE_PROPERTY_SUBSCRIPTION_SEGMENTS"
• "EXPORT_MESSAGE_PROPERTY_SENT"
• "EXPORT_MESSAGE_PROPERTY_OPENED"
• "EXPORT_MESSAGE_PROPERTY_ERRORS"
• "EXPORT_MESSAGE_PROPERTY_RECIPIENTS"
• "EXPORT_MESSAGE_PROPERTY_DELIVERED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_DELIVERED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_OPENED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_CLICKS"
• "EXPORT_MESSAGE_PROPERTY_CLICKS"
• "EXPORT_MESSAGE_PROPERTY_UNSUBSCRIBED"

properties is not just a filter

A property not listed in properties does not appear in the file at all, including the base columns (ID, send date, content, status). Leaving properties empty produces a CSV with no columns. List every column the export should contain, not only the metrics you want to add on top of a default set.

Example request

{
  "type": "TASK_TYPE_EXPORT_MESSAGES_V2",
  "export_messages_v2": {
    "application_code": "XXXXX-XXXXX",
    "filters": {
      "created_date": {
        "date_from": "2026-01-01",
        "date_to": "2026-06-30"
      },
      "statuses": ["MESSAGE_STATUS_DONE"],
      "platforms": [1, 3]
    },
    "properties": [
      "EXPORT_MESSAGE_PROPERTY_ID",
      "EXPORT_MESSAGE_PROPERTY_TIMESTAMP",
      "EXPORT_MESSAGE_PROPERTY_STATUS",
      "EXPORT_MESSAGE_PROPERTY_PLATFORMS",
      "EXPORT_MESSAGE_PROPERTY_SENT",
      "EXPORT_MESSAGE_PROPERTY_OPENED"
    ]
  }
}

200: OK

{
  "uid": "177458"
}

401: Incorrect API access token

{
  "error": "account not found"
}

status

Returns the progress of an export task.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/status

Request body parameters

Pass the task identifier returned by export:

Name	Required	Type	Description
uid	Yes	String (int64)	Task identifier from the export response, e.g. "177458".

Example request

{
  "uid": "177458"
}

200: OK

{
  "status": "STATUS_SUCCESS",
  "progress": 1
}

status is one of "STATUS_PENDING", "STATUS_SUCCESS", or "STATUS_FAILED". progress is a fraction between 0 and 1; poll status until it reaches "STATUS_SUCCESS" before calling result.

result

Returns the generated file name once the task has completed.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/result

Request body parameters

Pass the same task identifier returned by export:

Name	Required	Type	Description
uid	Yes	String (int64)	Task identifier from the export response, e.g. "177458".

Example request

{
  "uid": "177458"
}

200: OK

{
  "export_messages_v2_result": {
    "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv",
    "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
  }
}

Calling result before status reports "STATUS_SUCCESS" returns an empty result. file_url is a ready-to-use link to the download endpoint on the correct data center for the account — use it as-is instead of building the URL from file yourself. file_url is empty if the account’s data center has no base URL configured. In that case, you can only fall back to building the URL from file if the account is on the default app.pushwoosh.com data center — an account on another data center or a whitelabel domain has no way to derive the correct host from file alone.

lastTasks

Lists recent export tasks for an application, most recent first.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/lastTasks

Request body parameters

Every parameter is an optional filter; omit them all to list every task the token has access to:

Name	Required	Type	Description
application	No	String	Pushwoosh application code. Omit to list tasks across all applications the token has access to.
types	No	Array	Restrict to specific task types. Use [“TASK_TYPE_EXPORT_MESSAGES_V2”] to only see message exports.
campaign	No	String	Filter by campaign code.
message_id	No	String (uint64)	Filter by a single numeric message ID, quoted.
message_code	No	String	Filter by a single message code.
limit	No	Integer	Maximum number of tasks to return.
timestamp_from	No	String	Only return tasks created after this timestamp (RFC 3339).

Note

Tasks are kept for 30 days regardless of whether their file has already been deleted after the 7-day file retention window. lastTasks can still show a task whose result no longer resolves to a downloadable file.

Example request

{
  "application": "XXXXX-XXXXX",
  "types": ["TASK_TYPE_EXPORT_MESSAGES_V2"],
  "limit": 10
}

200: OK

{
  "tasks": [
    {
      "id": "177458",
      "timestamp": "2026-08-13T12:00:00Z",
      "status": "STATUS_SUCCESS",
      "requested_by_user": "user@example.com",
      "export_messages_v2": {
        "application_code": "XXXXX-XXXXX"
      },
      "export_messages_v2_result": {
        "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv",
        "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
      }
    }
  ]
}

delete

Deletes a task and its file before the 7-day retention window expires.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/delete

Request body parameters

Pass the task identifier returned by export:

Name	Required	Type	Description
uid	Yes	String (int64)	Task identifier from the export response, e.g. "177458".

Example request

{
  "uid": "177458"
}

200: OK

{}

Download

Downloads the CSV file generated by result, by name.

GET https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/<file>

Headers

Authenticate the same way as the other methods, or rely on an active Control Panel session:

Name	Required	Description
Authorization	Yes	Server API token, in the same format as the other exportMessagesStatistics methods: Authorization: Api <Server Key> (the Api scheme is case-insensitive). A request with no Authorization header and no logged-in Control Panel session gets 401 Unauthorized.

Replace <file> with the exact file value from the result response, for example:

https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv

Caution

Building this URL by hand only works for accounts on the default app.pushwoosh.com data center. An account on another data center (app.wavesend.ru for OVB, app.pushwoosh.us for IAD) or a whitelabel domain needs a different host, and there is no way to derive it from file alone. Use the file_url from result or lastTasks instead, because it already points at the right host for the account. See result for what to do if file_url comes back empty.

The file is a CSV containing the columns selected in properties. It stays available for 7 days after the export finishes, then the cleanup job removes it and the URL stops resolving.