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
  &query_scope=bright
  &accessToken={access_token}

Example (license seat report)

GET https://{bright-host}/bright/api/v2/stored_query/run.json
  ?name=redemptions_available_for
  &query_scope=bright
  &invitation_name=13708-14097-56871-91719-163f07ce-c3270a5d
  &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)

V3 invitation redemptions endpoint

REST alternative to the redemptions_available_for stored query. Returns the same seat-usage columns for license invitations in the API key’s realm.

GET /bright/api/v3/invitation/redemptions.json

Authentication: api_key or accessToken (user API key), or realm_guid + realm_secret_key (server-side only).

Query parameters — at least one filter is required:

Parameter	Description
`invitation_name`	License key string
`order_id`	One or more numeric order IDs (comma-separated in a single value)
`order_ids`	Comma-separated and/or repeated numeric order IDs (same parsing as `order_id`)

You may combine invitation_name with order_id / order_ids; all supplied filters are applied together.

Success body — JSON object with a top-level results array only (no meta). The shape depends on whether order_id / order_ids were sent.

Flat mode (`invitation_name` only, no `order_id` / `order_ids`)

results is a flat array of redemption rows (same columns as redemptions_available_for):

{
  "results": [
    {
      "license_key": "...",
      "order_id": 650,
      "created": "YYYY-MM-DD HH24:MI:SS",
      "seats_available": 2,
      "seats_used": 1,
      "title": "..."
    }
  ]
}

Batch mode (`order_id` / `order_ids` present, including with `invitation_name`)

results has one entry per requested order ID (sorted), each with its own HTTP status (RFC 4918–style Multi-Status in JSON):

{
  "results": [
    {
      "order_id": 650,
      "status": 200,
      "message": "Success",
      "data": [
        {
          "license_key": "...",
          "order_id": 650,
          "created": "YYYY-MM-DD HH24:MI:SS",
          "seats_available": 2,
          "seats_used": 1,
          "title": "..."
        }
      ]
    },
    {
      "order_id": 670,
      "status": 403,
      "message": "Not authorized for this order",
      "data": null
    }
  ]
}

Batch entry field	Meaning
`order_id`	The requested order ID
`status`	Per-order HTTP status code
`message`	Human-readable outcome
`data`	Array of redemption rows on success (`status` 200); `null` on error

Per-order item status codes

`status`	`message`	When
200	`Success`	Redemption rows returned, or order is accessible but has no rows (`data`: `[]`)
403	`Not authorized for this order`	Order exists in the realm, but the user API key is not `initiating_user` or in `reporting_users`
404	`Order not found`	No license invitation in the realm has that `order_id` in invitation `custom` JSON

HTTP status

Status	When
200	Flat mode success; or batch mode and every `results[]` entry has `status` 200
207	Batch mode and at least one `results[]` entry has a non-200 `status` (including when all requested orders fail)
400	No filter parameter; or `order_id` / `order_ids` was sent but contained no numeric IDs (`error`: `invitation_name, order_id, or order_ids is required` or `order_ids must be numeric`)
401	Missing/invalid authentication; or `invitation_name` was used and the user is not an invitation owner

Authorization

invitation_name only: Same invitation-owner rule as redemptions_available_for (initiating_user or reporting_users). Unauthorized users receive 401. Response uses flat mode; status is always 200 on success.
order_id / order_ids: Any authenticated user API key may call. Response uses batch mode. Rows are limited to invitations the user may report on; unauthorized orders appear as 403 entries and force 207 when any entry is non-200.
Realm credentials: All matching license invitations in the realm are returned. Unknown order IDs appear as 404 entries. Keep realm secrets server-side.

`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.

API Key — create a user access token before calling stored queries
Invitation — license keys use invitation_name; set initiating_user and reporting_users in invitation custom data for report access
Realm credentials — server-to-server authentication for initialize and trusted integrations

Using the $bright PHP object to call the Bright API Bright For WordPress
Bright User Meta Sync - Developer's Guide Bright For WordPress
Fetching Redemptions/Seats Available For A License… License Keys
Bright 2.0 Admin Beta User Guide Bright Admin Console
About the Bright E-Learning Dashboard Bright E-Learning Dashboard
template: bright-course-table Builtin Templates

Bright scoped stored queries — API reference

Run a query

Authentication

Invitation owner access

Administrator / reporter access

Realm credentials

Builtin queries

Quick reference

getLicenseKeysForUser

redemptions_available_for

V3 invitation redemptions endpoint

Flat mode (invitation_name only, no order_id / order_ids)

Batch mode (order_id / order_ids present, including with invitation_name)

invitation_completion_matrix

bright_completion_matrix

bright_completion_matrix_full

bright_completion_by_tag

brightCourseSummaryReport

brightLearningPathSummaryReport

registrations_by_course_for_realm

total_distinct_learners