docs
CTRL K
GitHubDiscord
DevelopersAPI ReferenceLearnIntegrationsWebsiteGitHubDiscord
Skip to Content

Analytics

Course analytics and usage metrics.

Check analytics configuration

GET/api/v1/analytics/status
User session only — API tokens not accepted

Returns whether the analytics backend (Tinybird) is configured on the server.

Error responses
  • 401 Authentication required
Request

Ingest a frontend analytics event

POST/api/v1/analytics/events
User session only — API tokens not accepted

Proxies a whitelisted analytics event from the frontend to the analytics backend. The authenticated user must belong to the target organization, and the event name must be in the allowed list.

Request bodyapplication/jsonrequired

event_namestringrequired
org_idintegerrequired
session_idstring
propertiesProperties
Error responses
  • 400 Invalid event name
  • 401 Authentication required
  • 403 User is not a member of the target organization
  • 422 Validation Error — HTTPValidationError
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Run a detail dashboard query

GET/api/v1/analytics/dashboard/detail/{query_name}
User session only — API tokens not accepted

Executes a predefined analytics detail query against Tinybird and enriches the result rows with course, activity, and user metadata from PostgreSQL. Requires org admin privileges.

Path parameters

query_namestringrequired

Query parameters

org_idintegerrequired
Error responses
  • 400 Invalid query parameter
  • 401 Authentication required
  • 403 User is not a member or admin of the organization
  • 404 Unknown detail query name
  • 422 Validation Error — HTTPValidationError
  • 502 Upstream analytics query failed
  • 503 Analytics backend is not configured
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Run a dashboard analytics query

GET/api/v1/analytics/dashboard/{query_name}
User session only — API tokens not accepted

Executes a predefined analytics query via Tinybird and returns the aggregated results. Advanced queries require an Enterprise plan. Requires org admin privileges.

Path parameters

query_namestringrequired

Query parameters

org_idintegerrequired
Error responses
  • 400 Invalid query parameter
  • 401 Authentication required
  • 403 User is not a member/admin, or plan does not permit advanced queries
  • 404 Unknown query name
  • 422 Validation Error — HTTPValidationError
  • 502 Upstream analytics query failed
  • 503 Analytics backend is not configured
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Run a PostgreSQL-backed dashboard query

GET/api/v1/analytics/dashboard/db/{query_name}
User session only — API tokens not accepted

Executes a predefined PostgreSQL analytics query (e.g. grade distribution histogram). Requires org admin privileges and a Pro plan or higher.

Path parameters

query_namestringrequired

Query parameters

org_idintegerrequired
Error responses
  • 401 Authentication required
  • 403 User is not admin or the organization lacks a Pro plan
  • 404 Unknown query name
  • 422 Validation Error — HTTPValidationError
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Run a course-level detail analytics query

GET/api/v1/analytics/dashboard/course/detail/{query_name}
User session only — API tokens not accepted

Executes a predefined course-level detail query via Tinybird with fallback to PostgreSQL TrailRun data, and enriches results with course, activity, and user metadata. Requires org admin privileges and a Pro plan or higher.

Path parameters

query_namestringrequired

Query parameters

org_idintegerrequired
course_uuidstringrequired
Error responses
  • 400 Invalid query parameter or course_uuid
  • 401 Authentication required
  • 403 User is not admin or the organization lacks a Pro plan
  • 404 Unknown course detail query name
  • 422 Validation Error — HTTPValidationError
  • 502 Upstream analytics query failed
  • 503 Analytics backend is not configured
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Run a course-level analytics query

GET/api/v1/analytics/dashboard/course/{query_name}
User session only — API tokens not accepted

Executes a predefined course-level analytics query via Tinybird and returns enriched aggregated results. Requires org admin privileges and a Pro plan or higher.

Path parameters

query_namestringrequired

Query parameters

org_idintegerrequired
course_uuidstringrequired
Error responses
  • 400 Invalid query parameter or course_uuid
  • 401 Authentication required
  • 403 User is not admin or the organization lacks a Pro plan
  • 404 Unknown course query name
  • 422 Validation Error — HTTPValidationError
  • 502 Upstream analytics query failed
  • 503 Analytics backend is not configured
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Export analytics data

GET/api/v1/analytics/export
User session only — API tokens not accepted

Exports results for a comma-separated list of analytics queries in either JSON or CSV format. Requires org admin privileges.

Query parameters

org_idintegerrequired
Error responses
  • 400 Invalid format, queries, or parameters
  • 401 Authentication required
  • 403 User is not admin of the organization
  • 422 Validation Error — HTTPValidationError
  • 502 Upstream analytics query failed
  • 503 Analytics backend is not configured
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Get analytics plan tier for an organization

GET/api/v1/analytics/plan-info
User session only — API tokens not accepted

Returns the analytics tier (core or advanced) available to the organization based on its current plan.

Query parameters

org_idintegerrequired
Error responses
  • 401 Authentication required
  • 403 User is not a member of the target organization
  • 422 Validation Error — HTTPValidationError
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}