The Insights API in Sana allows you to programmatically retrieve the same data that powers your custom dashboards.

This is ideal for automating reporting workflows, analyzing data outside of Sana (such as in BI tools), or pulling regular data snapshots for compliance and audits. With the API, you can export results from your Insights widgets using cURL or SQL.

Prerequisites

Before you begin, make sure you have:

A Sana account with access to the Insights feature (ideally as an admin)
- Permissions to create widgets and access data in Insights.
- Permissions to view all users needed in your use-case
Permissions to create an API client in Sana
- You will need this in order to get API access tokens for authentication.
- See how to get an access token

Preparing Your Data in Sana

1. Navigate to the Insights Page

Go to your Insights page:
- In Sana, find the Manage in the left navigation menu then select Insights

2. Create and Configure a Widget

Click Add widget to create a new widget.
Select the data you want to include in your report.
Apply any filters as needed to refine your data.

Tip: The widget builder lets you choose metrics, breakdowns, and filters for your report. Make sure your widget displays exactly the data you need.

Generating an API Request

3. Use Developer Tools to Copy the API Request

Once your widget is set up, click the </> button above the widget.
Click on the clipboard icon, then choose to copy the query as either:
- cURL – ready to run from your terminal or scripts.
  - Copying the cURL command is the fastest way to get a working API request.
- SQL – for use in constructing your requests with the Insights API.

Example cURL Request

curl -X POST 'https://<yourdomain>.sana.ai/api/v1/reports/query' \ 
-H 'Content-Type: application/json' \ 
-H 'Authorization: Bearer <your_token>' \ 
-d '{   "query": "SELECT \"user\", \"course\", \"start_date\", \"completion_date\", \"last_progress_date\", \"course_instance\" FROM \"analytics\".\"user_course_instance_progress\" ORDER BY \"user\"",   
"format": "csv" }'

⚠️NOTE: replace <yourdomain> and <your_token> with your actual Sana domain and API token.

Running the Report via the API

4. Send the API Request

Use the copied cURL command in your terminal or script.
The API endpoint is:
POST https://<yourdomain>.sana.ai/api/v1/reports/query
Required headers:
- Authorization: Bearer <your_token>
- Content-Type: application/json
Body parameters:
- query: The SQL query string (from your widget)
- format: Report format (csv or xlsx)

Example Response

{
   "data": {
     "jobId": "<job-id>",
     "status": "pending",
     "createdAt": "2024-09-04T13:23:30.478732Z",
     "startedAt": null,
     "finishedAt": null,
     "link": null   },
   "links": null,
   "error": null 
}

⚠️NOTE: the jobId' – you’ll use this to check the status of your report.

Checking Report Status

5. Poll the Job Status Endpoint

Use the job ID from the previous response.
Endpoint:
GET https://<yourdomain>.sana.ai/api/v1/reports/jobs/<job-id>
Required headers:
- Authorization: Bearer <your_token>
- Content-Type: application/json

Example cURL command

curl -X GET 'https://<yourdomain>.sana.ai/api/v1/reports/jobs/<job-id>' \
-H 'Content-Type: application/json' \ 
-H 'Authorization: Bearer <your_token>'

The status will be pending until the report is ready.

Repeat this request until the status is successful.

Example Successful Response

{
  "data": {
    "jobId": "<job-id>",
    "status": "successful",
    "createdAt": "2024-09-04T13:23:30.478732Z",
    "startedAt": "2024-09-04T13:23:33.029691Z",
    "finishedAt": "2024-09-04T13:23:33.748015Z",
    "link": {
      "url": "<download-url>",
      "expiresAt": "2024-09-04T13:41:31.632324923Z"
    }
  },
  "links": null,
  "error": null
}

Downloading the Report

6. Retrieve and Use the Download Link

When the job status is successful, the response will include a link.url field.
This is a temporary download link for your report.
Download the report before the expiresAt timestamp.

Example cURL command

curl -o report.csv '<download-url>'

This command downloads the report file from the given URL and saves it as report.csv in your current directory. Replace <download-url> with the actual link you received from the API response.

🎉 You’re now ready to generate and download reports from Sana using the Insights API!

If you need more advanced workflows or troubleshooting, consult the official Sana API documentation.

Troubleshooting & Tips

Common Issues:

Authentication errors: Ensure your API token is valid and has not expired.
Expired download link: If you miss the expiration window, rerun the report to generate a new link.
Query errors: Double-check your SQL syntax and widget configuration.

Best Practices:

Automate polling for job status in scripts to avoid manual checks.
Store reports securely, especially if they contain sensitive data.
Use filters in your widget to limit data to only what you need.

Frequently Asked Questions (FAQ)

Q: Can I use the API to schedule regular exports?
A: Yes, by scripting the API requests and scheduling them (e.g., with cron jobs), you can automate regular exports.

Q: What formats are supported for export?
A: CSV and XLSX formats are supported. Specify your preference in the format parameter.

Q: How do I get help if my API request fails?
A: Check the error message in the API response. For further assistance, contact Sana support or consult the API documentation.

Connecting LinkedIn Learning with Sana

Connecting Workday HRIS with Sana

Insights

Insights Metrics Guide

Insights: Best Practices