Export Report Data via Maxio API

Maxio provides a comprehensive API for running reports and exporting their data programmatically. Use it to automate recurring report pulls, sync report data into your own systems, or build custom integrations, instead of relying on the Maxio user interface to run and download reports manually.

The Reports API allows you to:

• Execute predefined reports or one-click reports.
• Monitor report execution status.
• Export report results in multiple formats.
• Retrieve exported files for download.

API endpoints overview

The Reports API uses the following base endpoints:

• Report Definitions: /{your-instance}/api/v1.0/reports/definitions/
• Report Runs: /{your-instance}/api/v1.0/reports/runs/
• Report Exports: /{your-instance}/api/v1.0/reports/exports/

Replace {your-instance} with your specific Maxio instance identifier. You can find this in your account settings or by checking the URL when logged into your Maxio dashboard.

Authentication

All API requests require proper authentication. Refer to the main API documentation for details on authentication methods and required headers. For complete API reference documentation, including all available parameters and response schemas, consult the OpenAPI documentation available in your Maxio instance.

Working with report definitions

Before running reports, you may want to explore what reports are available in your account. Report Definitions are read-only through this API. You can list and retrieve them, but creating, editing, or deleting a report definition requires the Maxio user interface.

Listing available reports

GET /{your-instance}/api/v1.0/reports/definitions/

Available Filters:

• name=Revenue - Filter by report name (partial match).
• description=monthly - Filter by description (partial match).
• type=financial - Filter by report type.
• tag=important - Filter by applied tags.
• one_click_report_group=uuid - Filter by one-click report group.
• created_by=123 - Filter by user who created the report.
• modified__gte=2025-01-01T00:00:00.000000 - Filter by modification date.

Sorting Options:

• id, name, description, type, created_by, one_click_report_group, modified

Getting report details

GET /{your-instance}/api/v1.0/reports/definitions/123/

This returns the complete structure of a specific report definition, including its configuration and parameters.

Basic workflow

Step 1: Run a report

To execute a report, make a POST request to /{your-instance}/api/v1.0/reports/runs/ with one of the following approaches:

Option A: Using a Report Definition ID

POST /{your-instance}/api/v1.0/reports/runs/
{
  "report_definition": 123,
  "export_format_name": "csv"
}

Option B: Using a One-Click Report UUID

POST /{your-instance}/api/v1.0/reports/runs/
{
  "one_click_report": "uuid-string-here",
  "export_format_name": "csv"
}

Available Export Formats:

• "csv" - Legacy CSV format
• "gsheets" - Legacy Google Sheets format
• "ucsv" - Unified CSV format
• "tgsheets" - Tabbed Google Sheets format
• "xlsx" - Excel format
• "xlsx1d" - OneDrive format

"ucsv" only works for reports built on the Generic Report Builder, such as Advanced Subscription Momentum, Finance Details by Transaction, and Days Sales Outstanding. Requesting it for any other report type fails.

The API response includes the run ID and URL for tracking progress:

{
  "id": "456",
  "url": "/api_path/reports/runs/456/"
}

Step 2: Monitor run status

Check the execution status by making a GET request to the run URL:

GET /{your-instance}/api/v1.0/reports/runs/456/

The response includes detailed status information:

{
  "id": 456,
  "status": "Completed",
  "duration_secs": "12.5",
  "timestamp": "2025-01-15T10:30:00Z",
  "user_full_name": "John Doe",
  "report_name": "Monthly Sales Report",
  "report_type": "sales_summary",
  "failure_message": null
}

Possible Status Values:

• "Running" - Report is currently executing.
• "Completed" - Report finished successfully.
• "Failed" - Report execution failed.

Wait until the status becomes "Completed" before proceeding to retrieve results.

Step 3: Retrieve report data

You have two options for accessing the report results:

Option A: Direct CSV Download (for smaller reports)

GET /{your-instance}/api/v1.0/reports/runs/456/?mode=csv

This streams the CSV data directly in the response. This method is ideal for smaller reports that can be processed immediately.

Option B: Create a Persistent Export (recommended for larger reports)

1. Create an export:

POST /{your-instance}/api/v1.0/reports/exports/
{
  "report_run": 456,
  "format_name": "csv"
}

2. Monitor the export status:

GET /{your-instance}/api/v1.0/reports/exports/789/

The response includes export details:

{
  "id": 789,
  "status": "Completed",
  "report_run": 456,
  "format_name": "csv",
  "timestamp": "2025-01-15T10:35:00Z",
  "url": "https://storage.example.com/exports/report_789.csv",
  "failure_message": null
}

Export Status Values:

• "Scheduled" - Export is queued for processing.
• "Running" - Export is being generated.
• "Completed" - Export is ready for download.
• "Failed" - Export generation failed.
• "Viewed" - Export has been accessed.

3. Once the export status is "Completed", retrieve the file:

GET /{your-instance}/api/v1.0/reports/exports/789/?redirect=1

The redirect=1 parameter redirects you directly to the downloadable file.

Option C: Row-Level JSON Results

Instead of a CSV or spreadsheet export, you can pull a run's results directly as structured JSON:

GET /{your-instance}/api/v1.0/reports/runs/456/results/

Without a section parameter, this returns the run's metadata plus the list of its sections (each section's name, label, and how deep its rows expand). Add ?section=<name> to also get that section's columns and one page of rows:

GET /{your-instance}/api/v1.0/reports/runs/456/results/?section=momentum&page=1&page_size=100

Available query parameters:

• section - A section's name from the sections list; omit it to see only that list.
• page - Page of rows to return (default 1).
• page_size - Rows per page (default 100, maximum 1000).
• expansion_level - Deepest row expansion level to include; omit for all levels.

Each row carries a row_key (either a stable database ID or a positional index — the run's store_in_db field tells you which), its key_values and result_values. The section's total_count is counted before paging, so you can tell when a page has cut off more rows. The response also carries definitional_basis: settings, such as Momentum Calculation Basis on the Advanced Subscription Momentum Report, that change what the figures themselves mean rather than just how they're grouped.

Like ucsv, this endpoint only works for reports built on the Generic Report Builder, such as Advanced Subscription Momentum, Finance Details by Transaction, and Days Sales Outstanding. Requesting it for another report type returns an error. If the run's stored results have already been purged, the endpoint returns a 410 response — run the report again to regenerate them.

Retaining a run's results via the API

By default, a report run's stored results are purged 5 days after it completes — the same window the Report History page's Retain option controls. To keep a specific run's results past that window from the API:

POST /{your-instance}/api/v1.0/reports/runs/456/retain/
{
  "keep": true
}

Set "keep": false to release a previously retained run back to the normal purge schedule. The response echoes the run's id, its keep_serialized_data flag, and its expires datetime (null while retained).

You can also turn on retention when you create the run, by adding "keep_serialized_data": true alongside report_definition or one_click_report in the initial POST /reports/runs/ request.

Managing reports and exports

Listing report runs

View all your report runs with optional filtering and sorting:

GET /{your-instance}/api/v1.0/reports/runs/

Available Filters:

• report_definition=123 - Filter by specific report definition ID.
• one_click_report=uuid - Filter by one-click report UUID.
• status=Completed - Filter by status (Running, Completed, Failed).
• user=456 - Filter by user ID who ran the report.
• report_name=Sales - Filter by report name (partial match).
• report_type=summary - Filter by report type.
• timestamp__gte=2025-01-01T00:00:00.000000 - Filter by date range (after).
• timestamp__lt=2025-02-01T00:00:00.000000 - Filter by date range (before).

Sorting Options:

Use the sort parameter with any of these fields:

• timestamp - Sort by execution time.
• duration_secs - Sort by execution duration.
• user - Sort by the ID of the user who ran the report.
• user_full_name - Sort by user name.
• report_name - Sort by report name.
• report_type - Sort by report type.
• data_format - Sort by data format.
• report_definition - Sort by report definition ID.
• status - Sort by status.

Example with filters:

GET /{your-instance}/api/v1.0/reports/runs/?status=Completed&report_type=sales&sort=timestamp

Listing exports

Similarly, you can list and filter exports:

GET /{your-instance}/api/v1.0/reports/exports/

Available Filters:

• report_run=456 - Filter by specific report run ID.
• report_definition=123 - Filter by report definition ID.
• status=Completed - Filter by export status.
• format_name=csv - Filter by export format.
• report_name=Monthly - Filter by report name (partial match).
• report_type=summary - Filter by report type.
• timestamp__gte=2025-01-01T00:00:00.000000 - Filter by date range.

Sorting Options:

• report_run, report_definition, timestamp, format_name, report_name, report_type, status

Example:

GET /{your-instance}/api/v1.0/reports/exports/?status=Completed&format_name=csv&sort=timestamp

Best practices

1. Choose the Right Approach: Use export_format_name when creating a report run to automatically trigger export creation, especially for larger datasets.
2. Don't Mix Report Types: Specify either report_definition or one_click_report when creating a run, but never both.
3. Poll Responsibly: When monitoring status, implement reasonable polling intervals (e.g., every 5-10 seconds) to avoid overwhelming the API.
4. Handle Large Reports: For reports that may generate large datasets, always use the persistent export approach rather than direct CSV streaming.
5. Use Filtering: Take advantage of the filtering parameters when listing runs and exports to find specific results quickly.
6. Date Format Consistency: When using datetime filters, always use the format YYYY-MM-DDTHH:MM:SS.000000 (e.g., 2025-01-15T14:30:00.000000).
7. Pagination: Use the page parameter for large result sets and check the next and previous URLs in responses for navigation.

Error handling

Common scenarios to handle in your implementation:

• Invalid Report IDs: Ensure your report definition IDs are valid and accessible.
• Long-Running Reports: Some reports may take several minutes to complete - implement appropriate timeout handling.
• Export Failures: Check export status and handle failed exports appropriately by examining the failure_message field.
• Rate Limiting: Implement proper retry logic with exponential backoff for API requests.
• Empty Results: Handle cases where reports complete successfully but contain no data.

Troubleshooting

Report run fails

• Check that the report definition ID exists and is accessible to your user.
• Verify that editable report definitions are being used (some reports may be read-only).
• Review the failure_message field in the response for specific error details.

Export never completes

• Monitor the export status regularly.
• Check system status if exports remain in "Running" state for extended periods.
• Contact support if exports consistently fail with specific report types.

Direct CSV download issues

• Use the mode=csv parameter only for smaller reports.
• Switch to persistent exports for large datasets.
• Ensure the report run status is "Completed" before attempting CSV download.

Related information

For an overview of exporting data from Maxio, including how to initiate an export from the user interface, see Understand Data Export.