Summary
The Reporting API allows authorized Admin users to generate and download exportable reports automatically. It’s designed for integrations with internal dashboards, BI tools, or automated workflows that require scheduled access to reporting data.
What is it
A REST API that supports asynchronous report generation and download.
When to use it
You need to automate report exports (e.g., weekly reporting to internal stakeholders)
You want to integrate Second Nature data with internal systems or BI dashboards
You manage multiple accounts and need centralized report access
Who is it for
Admin-level users with API access
Internal analytics/data teams or IT departments
Note: API authentication must be performed using an Admin user associated with the company accessing the API. This ensures proper permission enforcement, traceability, and support.
Authentication
Every API request must include your API key in the request header.
For authentication info, see here.
How It Works
For technical information, see here - Export_Report_API_V0.pdf.
1. Request a Report
Submit a report generation request. You’ll receive a ticket_id in return.
Required: report_name (see “Get List of Available Reports”)
Optional: filters such as course_id, time range (in UTC), and a force_update flag to bypass cache
Use the returned ticket_id in the next step.
2. Track Report Status and Download
Use the ticket_id to:
Track generation status (pending, in_progress, complete, or failed)
Access the download link when the report is complete (report_url)
Report generation is asynchronous. It’s recommended to poll every 15–30 seconds until the report is ready.
3. Get List of Available Reports
You can request a list of valid report names to ensure you’re using a supported value for report_name.
Example Use Case
Your operations team wants to pull a course completion report every Monday:
Use the API to request admin-xls-report
Poll for the report status
When complete, download the report from the report_url
This process can be automated using:
Python scripts and scheduled jobs (e.g., cron)
Webhook tools like Zapier or Make
Internal integration pipelines
Troubleshooting
Problem | Likely Cause | Recommended Action |
401 Unauthorized | API token missing or invalid | Confirm you’re using a valid Admin token |
403 Forbidden | User lacks necessary permissions | Confirm the token belongs to an Admin user |
404 Not Found | Report name or course ID is incorrect | Verify report_name and course_id values |
Status = failed | Report generation encountered an error | Retry the request or contact support with details |
Considerations
Time filters must use UNIX timestamp format in UTC.
Download URLs are temporary and should be accessed promptly.
Not all reports support all optional filters; refer to technical documentation for details.
Multi-Sheet Report Exports
Some reports contain multiple tabs (sheets) when exported in Excel format. The behavior differs slightly depending on the export format:
XLSX: The report includes multiple sheets within a single file.
CSV: Each sheet is exported as a separate CSV file.
JSON: If the XLSX version of the report includes multiple sheets, the JSON export will include a reports array — one object per sheet.
Each object includes:
report_name: The name of the report (same for all sheets)
sheet_name: The name of the specific sheet
data: An array of records representing the rows in that sheet
FAQ
Q: Can non-admins use the Reporting API?
A: No. Only Admins and Multi-Company Admin users associated with your company can access the API.
Q: What format are the reports in?
A: Reports are exported as .xlsx by default, however, CSV and JSON formats are also supported.
Q: How long are report download links valid?
A: Links are temporary. If a link expires, you can regenerate the report by creating a new ticket.
Q: Does the API key need to be sent in a password protected doc and the password sent in a separate email?
A: No. The API Key can be sent as it is, on a seperate email, no password protection required.