Export History
Export History shows report exports that were created as background jobs. Use it to check whether an export is pending, processing, completed, or failed, and to download completed export files.Track export jobs
See all report export jobs with status, format, date range, report type, and creation date.
Download completed files
Download completed exports when the file is ready.
Filter and refresh
Filter by status, file format, and creation date, or refresh the table manually.
Access Export History
Export History is opened from the reports area. Use it after creating a background export from a report page, such as the Purchase Orders Report.What Export History shows
The export history table shows report export jobs for the selected company context. Each row can show:| Column | Description |
|---|---|
| Format | Export file format, such as CSV or PDF |
| Date range | The report period covered by the export |
| Report type | The type of report that was exported |
| Status | Current export job status |
| Created | When the export job was created |
| Download | Download button, shown only when the export is completed and downloadable |
File format badges
Export files are shown with visual badges.| Format | Badge |
|---|---|
| CSV | Green spreadsheet badge |
| Blue document badge |
Statuses
Export jobs can have different statuses.| Status | Meaning |
|---|---|
pending | The export job was created and is waiting to be processed |
processing | The export job is currently being generated |
completed | The export finished successfully and can be downloaded if a file is available |
failed | The export failed. The error message may be shown below the failed badge |
Automatic refresh
Export History automatically refreshes while there are unfinished jobs. Unfinished jobs are jobs that are not yet:completedfailed
Downloading an export
Completed exports show a Download button when the job is downloadable.Download is only shown when the export status is
completed and the job can be downloaded.Filters
Export History supports filters in the toolbar.| Filter | Description |
|---|---|
| Status | Filter by one or more export statuses |
| Format | Filter by CSV or PDF |
| Created | Filter by export creation date range |
URL search parameters
The frontend keeps filter, sorting, and pagination state in the URL.| Parameter | Description |
|---|---|
page | Current page, starting at 0 |
page_size | Number of rows per page, from 1 to 200 |
ordering | Sort order, such as -created_at |
status | Comma-separated statuses |
file_format | Comma-separated file formats |
created_from | Created date filter start |
created_to | Created date filter end |
| Setting | Default |
|---|---|
ordering | -created_at |
page_size | 20 |
Sorting
The table supports sorting for selected columns. Sortable columns include:- Format
- Date range
- Report type
- Status
- Created
ordering URL parameter and resets the table to the first page.
Pagination
Export History is paginated. The backend returns:| Field | Meaning |
|---|---|
results | Export jobs for the current page |
page | Current page |
page_size | Number of rows per page |
total | Total number of matching export jobs |
total_pages | Total number of pages |
Creating an export job
Export jobs are created from report pages, such as the purchase report. For example, a report page can create a background export job with:| Field | Meaning |
|---|---|
company_id | Company that owns the export job |
date_from | Start date for the export period |
date_to | End date for the export period |
file_format | Export format, such as CSV or PDF |
report_type | Report type. If omitted, the backend defaults to delivery_location |
pending.
The backend then queues the report export task for processing.
Direct download vs background export
Some report pages can support both direct downloads and background exports.| Action | Behavior |
|---|---|
| Direct CSV or PDF download | The report file is generated and downloaded immediately from the report endpoint |
| Background export job | A job is created and later appears in Export History |
Backend list behavior
The backend lists export jobs through the export job endpoint. It supports:- Pagination
- Company filtering
- Status filtering
- Report type filtering
- File format filtering
- Created date range filtering
- Ordering
Backend filters
The backend accepts these filters for export jobs:| Query parameter | Description |
|---|---|
company_id | Limit results to one company |
status | Filter by one or more statuses |
report_type | Filter by one or more report types |
file_format | Filter by one or more file formats |
created_at_from | Filter jobs created on or after this date |
created_at_to | Filter jobs created on or before this date |
ordering | Sort order |
page | Page number |
page_size | Page size |
The frontend uses
created_from and created_to; the backend export-job endpoint uses created_at_from and created_at_to. The API hook should translate these values before calling the backend.Backend ordering
The backend supports ordering by:| Field |
|---|
created_at |
updated_at |
status |
date_from |
date_to |
id |
report_type |
file_format |
Access control
Export jobs are restricted by financial-report access. A user can only list, create, or download export jobs for companies where they have the required financial viewing capability. If the user does not have access, Mathership returns an access error.Download backend behavior
When a user downloads a completed export, the backend:- Checks that the job belongs to a company the user can access
- Confirms that the user has permission to view financial data
- Checks that the job status is
completed - Checks that a file key exists
- Generates a secure pre-signed S3 download URL
- Returns the download URL, expiry time, and filename
| Response field | Meaning |
|---|---|
download_url | Temporary secure URL for the exported file |
expires_in_seconds | Download URL lifetime, currently 3600 seconds |
filename | Suggested filename for the downloaded ZIP file |
Download errors
| Situation | Result |
|---|---|
| Job is not completed | Download is rejected because the report is not ready |
| No file key exists | Download is rejected because no file is available |
| S3 URL generation fails | Backend returns a server error |
| User lacks access | Backend returns an authorization error |
Empty and loading states
The frontend can show:| State | Behavior |
|---|---|
| Loading | Table shows loading state while export jobs are fetched |
| No rows | Table is empty when no jobs match the current filters |
| Failed job | Failed badge is shown, with error message if available |
| Processing job | Processing badge is shown, with progress if available |
Common workflows
Create and download a report export
- Open a report page
- Select the required filters, such as date range and delivery location
- Create the export job
- Open Export History
- Wait until the job status is Completed
- Click Download
Check why an export failed
- Open Export History
- Filter by status Failed
- Find the failed job
- Review the error message shown under the failed badge
- Recreate the export after correcting the report filters or data issue
Find a specific export
- Open Export History
- Filter by file format if you know whether it was CSV or PDF
- Filter by created date range
- Sort by Created or Date range
- Download the completed file
Best practices
Use background exports for larger reports
Create export jobs for reports that may take longer to generate.
Check status before downloading
Download is only available after the export reaches Completed.
Refresh when needed
Use the Refresh button if you want to check the latest job status immediately.
Use filters
Filter by status, format, and creation date to find older exports quickly.
Download soon
Secure download URLs expire after 1 hour.
Check permissions
Users need financial-report access for the company to list, create, or download exports.
Common problems
Download button is not visible
Download button is not visible
Export is stuck in pending or processing
Export is stuck in pending or processing
Click Refresh to reload the latest status.If the status does not change for a long time, the export task may need backend review.
Export failed
Export failed
Review the error message shown under the failed badge.Create the export again after correcting the report filters or underlying data issue.
Download link expired
Download link expired
Click Download again from Export History to request a new secure download URL.
I cannot see exports for a company
I cannot see exports for a company
Check that you selected the correct company and that your user has permission to view financial reports for that company.
Related pages
Inventory Report
Review stock levels, movement history, costs, and ingredient activity.
Purchase Orders Report
Analyze received vendor order data by delivery location and date range.
Delivery Locations
Manage delivery locations used by purchase reports.
Organization Settings
Manage organizations, companies, members, and access permissions.