Workspace admins can generate monthly payout and transfer fee reports for specific apps. The report summarizes fees for a past billing month and delivers a CSV download link to a specified recipient via email.
This is an internal admin workflow. Access is restricted to API keys with admin-level permissions on the app. Standard dashboard users cannot trigger this report.
The monthly payout fee report endpoint requires:
An API key with admin-level access (auth_level >= 2)
The API key's associated app must have admin privilegesenabled
If your API key lacks these permissions, the request will be rejected with an authentication error.
Submit a POST request to the tooling endpoint with the required fields:
POST /monthly-payout-fee-reportField | Type | Description |
|---|---|---|
| UUID | The app ID to generate the reportfor. |
| Date | The billing month in ISO format (YYYY-MM-DD). Must be the first day of a past month. |
| Email address to receive the download link. | |
| String | Identifier for the report (lowercase alphanumeric with underscores, 2-40 characters, must start and end with alphanumeric). |
The billing_month field has strict requirements:
Must be in the past — You cannot request a report for the current month or future months.
Must be the first day of the month — Use format YYYY-MM-01 (e.g., 2024-11-01 for November 2024).
If you submit a date like 2024-11-15, you'll receive an error: "billing_month must be the first day of the month." The correct format is 2024-11-01.
The label field must match the pattern ^[a-z0-9][a-z0-9_]{0,38}[a-z0-9]$:
Lowercase letters, numbers, and underscores only
Starts and ends with an alphanumeric character
Length: 2-40 characters
Examples: finance_report, ops2024, monthly_summary
{
"api_app_id": "550e8400-e29b-41d4-a716-446655440000",
"billing_month": "2024-10-01",
"recipient_email": "[email protected]",
"label": "finance_report"
}The endpoint queues the report generation asynchronously and returns immediately:
Successful response: HTTP 200 with an empty body
Report is not returned inline — Generation happens in the background
Download link is emailed — The recipient receives a presigned S3 link via email
Do not poll for completion. The report will be delivered to therecipient email address once generated.
The report is uploaded to anS3 bucket derived from the label:
{label-with-dashes}-transfer-reportsFor example, iflabel is finance_report, the bucket name becomes finance-report-transfer-reports.
The CSV filename follows this pattern:
monthly_fees_{label}_{billing_month}_{generated_at}.csvExample: monthly_fees_finance_report_2024-10-01_2024-11-15T10:30:00.csv
The recipient receives an email with:
Subject: {Pretty Label} Monthly Fee Report: {billing_month}
Body: A download link and the generation timestamp
Link text shows expiry time in hours
The download link expiration depends on the AWS credentials configuration:
Credential Type | Link Validity |
|---|---|
Permanent AWS credentials | 7 days |
Assumed-role credentials | 1 hour |
Federated credentials | 2 hours |
Default/fallback | 6 hours |
Production environments typically use permanent AWS credentials, resulting in 7-day link validity. Contact your infrastructure team to confirm your organization's configuration.
Common causes:
billing_month is not the first day of the month — UseYYYY-MM-01 format
billing_month is not in the past — You cannot request reports for the current or future months
label contains invalid characters — Use only lowercase letters, numbers, and underscores
label starts or ends with a non-alphanumeric character
Verify that:
Your API key has auth_level >= 2
Your API app has admin privileges enabled
Standard dashboard API keys do not have access to this endpoint.
The report generates asynchronously. If you don't receive the email:
Check spam/junk folders
Verify therecipient_email address is correct
Check that the S3 bucket exists with correct IAM permissions
Confirm the task ran in a production environment— report generation is skipped in non-production environments