Bright scoped stored queries — API reference

Builtin reporting queries run through the Stored Query API. Each query is invoked by name with query_scope=bright. The server applies your API key’s realm context automatically; you supply the query name and any query-specific parameters.

Run a query

Request

GET /bright/api/v2/stored_query/run

POST /bright/api/v2/stored_query/run

Query parameters

Parameter	Required	Description
`name`	Yes	Builtin query name (see table below)
`query_scope`	Yes	Must be `bright`
`accessToken`	Yes*	User or site API key (`api_key` is accepted as an alias)
`format`	No	`json` (default), `csv`, or `xml`
`callback`	No	JSONP callback name

* Alternatively authenticate with realm credentials (realm_guid + realm_secret_key) for server-side integrations; see Authentication.

Example (user API key)

GET https://{bright-host}/bright/api/v2/stored_query/run.json
  ?name=getLicenseKeysForUser
  &amp;query_scope=bright
  &amp;accessToken={access_token}

Example (license seat report)

GET https://{bright-host}/bright/api/v2/stored_query/run.json
  ?name=redemptions_available_for
  &amp;query_scope=bright
  &amp;invitation_name=13708-14097-56871-91719-163f07ce-c3270a5d
  &amp;accessToken={access_token}

Success response

HTTP 200
Body: JSON array of result rows (each row is an array of column values in column order). CSV and XML are also supported via format.

Error responses

HTTP	Meaning
401	Invalid, expired, or missing API key; or the key is not permitted to run this query
404	Unknown query `name`, or query not initialized on this environment

Authentication

Obtain a user access token by creating an API key for that user (see API Key create with user_email, realm_guid, and realm_secret_key).

Access level	Who can use it	Typical queries
Authenticated user	Any valid user API key	`getLicenseKeysForUser`
Invitation owner	User whose email matches the invitation’s purchaser or reporting list	`redemptions_available_for`, `invitation_completion_matrix`
Administrator	User with administrator or owner role on the realm, or a realm-level API key (no user bound)	Completion and summary reports
Anonymous	Site anonymous API key only	`total_distinct_learners`

Invitation owner access

For redemptions_available_for and invitation_completion_matrix, the API key’s user must match the invitation identified by invitation_name:

initiating_user — email of the purchaser (in invitation custom JSON), or
reporting_users — comma-separated list of emails allowed to view the report (in invitation custom JSON)

If neither matches, the request returns 401 even with a valid access token.

Administrator / reporter access

Admin-only queries may also allow users with reporter or administrator role on the site that sent the request. Pass the site URL as host_url when calling from a plugin or integration.

Realm credentials

Trusted server integrations may call stored_query/run with realm_guid and realm_secret_key instead of accessToken. This bypasses per-user permission checks. Do not expose realm secret keys in browser-side code.

Builtin queries

Quick reference

Query name	Access level	You provide	Result highlights
`getLicenseKeysForUser`	Authenticated user	—	License key names and course titles for the current user
`redemptions_available_for`	Invitation owner	`invitation_name`	Seats available and seats used for one license key
`invitation_completion_matrix`	Invitation owner	`invitation_name`	Learner completion rows for one license key
`bright_completion_matrix`	Administrator	`guid_prefix`	Completion matrix for courses matching a GUID prefix
`bright_completion_matrix_full`	Administrator	—	Full realm learner × course completion matrix
`bright_completion_by_tag`	Administrator	`provider_tags`	Completion rows for courses with matching tags
`brightCourseSummaryReport`	Administrator	—	Per-course registration and completion statistics
`brightLearningPathSummaryReport`	Administrator	`path_name`	Per-step learning path statistics
`registrations_by_course_for_realm`	Administrator	—	Registration count per course
`total_distinct_learners`	Anonymous	—	Count of distinct learners (requires anonymous API key)

Parameters realm_id, course_provider_id, and user are set by the server from your API key; you do not pass them unless building a custom integration that documents otherwise.

`getLicenseKeysForUser`

List license invitations assigned to the authenticated user.


Access	Authenticated user
Parameters	None beyond `name` and `query_scope`
Columns	`name`, `realm_id`, `email`, `title`

`redemptions_available_for`

Seat usage for a single license key (invitation).


Access	Invitation owner (`initiating_user` or `reporting_users`)
Parameters	`invitation_name` — the license key string
Columns	`license_key`, `order_id`, `created`, `seats_available`, `seats_used`, `title` (per course row)

`invitation_completion_matrix`

Detailed completion data for learners registered under one license key.


Access	Invitation owner
Parameters	`invitation_name`
Columns	`learner_id`, `title`, `complete`, `success`, `score`, `completed_at`

`bright_completion_matrix`

Completion report for courses whose course_guid starts with a prefix.


Access	Administrator (optionally reporter with `host_url`)
Parameters	`guid_prefix` — prefix to match against `course_guid`
Columns	`learner_id`, `title`, `complete`, `success`, `score`, `completed_at`, `totaltime`

`bright_completion_matrix_full`

Matrix of all realm users against all active courses, with registration data where present.


Access	Administrator
Parameters	None
Columns	`email`, `title`, `complete`, `success`, `score`, `completed_at`

`bright_completion_by_tag`

Completion rows for courses matching a provider tag string.


Access	Administrator
Parameters	`provider_tags` — substring matched against `courses.provider_tags`
Columns	`learner_id`, `title`, `complete`, `success`, `score`, `completed_at`

`brightCourseSummaryReport`

Aggregated statistics per course in the realm.


Access	Administrator
Parameters	None
Columns	`title`, `total_registrations`, `num_complete`, `pct_complete`, `num_passed`, `pct_passed`, `num_failed`, `pct_failed`, `avg_score`, `avg_total_time_mins`

`brightLearningPathSummaryReport`

Aggregated statistics per learning-path step.


Access	Administrator
Parameters	`path_name` — learning path key stored in course custom JSON
Columns	`title`, `path_step`, `total_registrations`, `num_complete`, `pct_complete`, `num_passed`, `pct_passed`, `num_failed`, `pct_failed`, `avg_score`, `avg_total_time_mins`

`registrations_by_course_for_realm`

Registration counts grouped by course, ordered by count descending.


Access	Administrator
Parameters	None
Columns	`title`, `course_guid`, `num_registrations`

`total_distinct_learners`

Count of distinct learners for the API key’s course provider.


Access	Anonymous site API key
Parameters	None (uses `course_provider_id` from context)
Columns	`count`

Initialize queries (admin)

On a new Bright Server environment, builtin query definitions must be loaded once.

GET /bright/api/v2/stored_query/initialize

Authentication: realm_guid + realm_secret_key only.

Response: JSON array of query names that were created or updated.

Bright scoped stored queries — API reference