Generate Your First Report

Use the signed-in Connect dashboard for customer reports, or use the partner session and xAPI endpoints when reporting belongs in your own product.

Choose the Right Reporting Surface

/api/customer/* endpoints are dashboard routes. They use the signed-in Clerk session and must not be called with an API key from a backend integration.

Learner Progress in the Dashboard

Open Dashboard → Reports → Learner progress. The page reads:

GET /api/customer/reports/learner-progress
Cookie: <Clerk session>

The route does not accept a range parameter. Its response is:

{
  "summary": {
    "totalSessions": 2,
    "completedSessions": 1,
    "passedSessions": 1,
    "inFlightSessions": 1,
    "averageProgress": 75
  },
  "rows": [
    {
      "sessionId": "550e8400-e29b-41d4-a716-446655440001",
      "learnerName": "Learner 123",
      "learnerRef": "learner-123",
      "packageId": "pkg_abc123",
      "packageTitle": "Safety Fundamentals",
      "sessionStatus": "active",
      "completionStatus": "incomplete",
      "progressPercent": 50,
      "lastActivityAt": "2026-09-01T12:00:00.000Z",
      "source": "api"
    }
  ],
  "count": 1
}

Export Learner Progress

The CSV export supports optional filters:

GET /api/customer/reports/learner-progress/export?days=30&organizationId=org_123&dispatchId=dsp_123
Cookie: <Clerk session>

• days: positive integer lookback window
• organizationId: one organization in the current workspace
• dispatchId: sessions associated with one dispatch's package

The response is text/csv and downloads as connect-learner-progress.csv.

Custom Reports

Custom reports are GET-only. Supported type values are sessions, packages, dispatches, and webhooks; an omitted or unknown type resolves to sessions.

const response = await fetch('/api/customer/reports/custom?type=dispatches', {
  credentials: 'include',
});

if (!response.ok) throw new Error('Report request failed');
const report = await response.json();
// { kind, title, columns, rows, filename, count }

Download the same dataset as CSV:

window.location.assign('/api/customer/reports/custom/export?type=dispatches');

There is no POST /api/customer/reports/custom, and custom-report routes do not accept arbitrary date-range or grouping payloads.

Partner API Reporting

API keys use the partner surface. The supported scopes are public_api, internal_product, and admin.

curl "https://app.allureconnect.com/api/v1/sessions?package_id=pkg_abc123&limit=100" \
  -H "Authorization: Bearer $CONNECT_API_KEY"

The session list returns { "sessions": [...], "pagination": {...} }. Use the response's camelCase fields as documented in the API reference; do not invent report fields from the dashboard CSV.

For statement-level reporting, use the xAPI LRS:

curl "https://app.allureconnect.com/api/v1/xapi/statements?actor_mbox=mailto%3Alearner%40example.com&limit=25" \
  -H "Authorization: Bearer $CONNECT_API_KEY" \
  -H "X-Experience-API-Version: 1.0.3"

The statement endpoint supports statement_id, actor_mbox, verb_id, activity_id, session_id, package_id, page, and limit (25 by default, 500 maximum). See the API reference for the write and analytics endpoints.

Empty and Error States

• Empty workspaces return an honest empty rows array and count: 0.
• Invalid or missing Clerk sessions return an authentication error on customer routes.
• Invalid API keys on partner routes return the flat error shape { "error": "…", "code": "API_KEY_REQUIRED" }.
• Check X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset when a rate-limited endpoint responds with 429.

Next Steps

• Quick Start
• Launch Your First Session
• API Reference
• Webhook Setup