AsRun
Overview
The AsRun API provides programmatic access to post-broadcast logs and reports.
It allows clients to: - retrieve raw AsRun log entries for a day, page by page - apply saved or ad-hoc filters - generate reports in JSON or CSV format - manage saved AsRun filters (create, update, delete)
Base path
/api/asrun
Note
Every route on this page requires Admin rights. A request from a non-admin user is refused with 403 and {"error": "Forbidden"}.
An AsRun line is written when a page is taken in or out on the [PROGRAM] channel of a profile, or on a channel addressed by name. Nothing is logged for [PREVIEW]. See On-Air Actions on a Profile for the calls that produce these lines.
AsRun depends on the server Log Level
AsRun lines are written at TRACE, and every route on this page reads back only entries at that level. If the Studio Server's Log Level (Settings → Global Settings → General → Logs) is set to Info, Warning or Error, these routes return an empty list and reports come back empty, with no error. Set the Log Level to Trace on any server whose AsRun record matters.
AsRun Action
The message of an AsRun log line, and the action of a filter, is one of:
| Value | Description |
|---|---|
TAKE_IN |
The page was taken on air |
TAKE_OUT |
The page was taken off air |
Get AsRun logs
GET /api/asrun/logs
Returns a page of raw AsRun log lines for a day.
Request
| Parameter | Type | Description |
|---|---|---|
| day | String (query) | Day to read (YYYY-MM-DD). Defaults to today |
| ref | Number (query) | Byte offset of the first line to return, as given by Get AsRun log pages. Defaults to 0 |
| id | String (query) | Log set id. Leave empty for the main AsRun log |
| filter | String (query) | Name of a saved filter to apply. Unknown names are ignored and all lines are returned |
Response
The response is an array of log lines. meta holds ids, not names: show is the Show id, profile the Profile id, channel the _id of the channel inside that profile, and page the page name.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | |
Get AsRun log pages
GET /api/asrun/logs/pages
Returns the paging information for a day's AsRun log. Each entry gives a ref to pass to Get AsRun logs.
Request
| Parameter | Type | Description |
|---|---|---|
| day | String (query) | Day to read (YYYY-MM-DD). Defaults to today |
| id | String (query) | Log set id. Leave empty for the main AsRun log |
| filter | String (query) | Name of a saved filter to apply |
Response
1 2 3 4 5 6 7 8 9 10 11 12 | |
Get logs using a custom filter
POST /api/asrun/logs/filter
Returns every AsRun log entry of a day that matches a filter definition supplied in the request body. The whole day is scanned, so no ref is needed.
Request
| Parameter | Type | Description |
|---|---|---|
| day | String (query) | Day to read (YYYY-MM-DD). Defaults to today |
The body is a filter definition. show, profile and channel are compared against the ids stored in the log line, and action against the AsRun Action enum.
1 2 3 4 5 6 7 8 | |
Response
The response is an array of log lines, in the same shape as Get AsRun logs.
Generate an AsRun report
Generates an AsRun report for one day, either from a saved filter or from an ad-hoc filter given as query parameters. Both routes answer with a file attachment.
Note
Reports can be generated only for one day at a time.
| Format | Request |
|---|---|
| JSON | GET /api/asrun/filters/[FILTER]/logs?day=YYYY-MM-DD |
| CSV | GET /api/asrun/filters/[FILTER]/csv?day=YYYY-MM-DD |
Request
| Parameter | Type | Description |
|---|---|---|
| FILTER | String (path) | Name of the saved filter. Use the literal undefined to filter with the query parameters below instead |
| day | String (query) | Report date (YYYY-MM-DD). Defaults to today |
| show | String (query) | Only when FILTER is undefined: Show id |
| profile | String (query) | Only when FILTER is undefined: Profile id |
| channel | String (query) | Only when FILTER is undefined: channel id |
| action | String (query) | Only when FILTER is undefined: TAKE_IN or TAKE_OUT |
| from | String (query) | Only when FILTER is undefined: start time of day (HH:mm) |
| to | String (query) | Only when FILTER is undefined: end time of day (HH:mm) |
The attachment is named Report_[FILTER]_[yyyy_mm_dd].json / .csv, or Report_[yyyy_mm_dd].json / .csv when FILTER is undefined.
In both formats the ids stored in the log are resolved to names: show becomes path/name of the show, profile the profile name, channel the channel name, and the action is the second half of the log message capitalised, so TAKE_IN becomes In and TAKE_OUT becomes Out. time is the full log timestamp.
JSON response example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | |
CSV report example
The CSV file is UTF-8 with a byte order mark and CRLF line endings.
1 2 3 | |
Errors
If the saved filter does not exist the request fails with 500:
1 2 3 4 | |
AsRun Filter
Saved filters are kept in AsRun.json in the Studio Server data folder, not in the database. A filter has the following properties:
| Property | Type | Description |
|---|---|---|
| name | String | Filter name. Required, and unique (case-insensitive) |
| scheduled | Boolean | Include this filter in the scheduled AsRun job, which writes a CSV report per filter into the AsRun folder |
| from | String | Only keep lines at or after this time of day (HH:mm) |
| to | String | Only keep lines at or before this time of day (HH:mm) |
| action | String | TAKE_IN or TAKE_OUT |
| show | String | Show id |
| profile | String | Profile id |
| channel | String | Channel id, as stored in channels._id of the profile |
Every property except name is optional; an omitted property is not used to filter.
Get all AsRun filters
GET /api/asrun/filters
Returns all stored AsRun filters, sorted by name.
Response
1 2 3 4 5 6 7 8 9 10 11 12 | |
Get an AsRun filter
GET /api/asrun/filters/[FILTER]
Returns one saved filter. The name is matched case-insensitively.
Request
| Parameter | Type | Description |
|---|---|---|
| FILTER | String (path) | Filter name |
Response
The filter object, or 404 if no filter of that name exists:
1 2 3 4 | |
Create an AsRun filter
POST /api/asrun/filters
Creates a new AsRun filter. The body is a filter object.
Request
1 2 3 4 5 6 7 8 9 10 | |
Response
The created filter. An empty or missing name fails with 500 and Filter must contain a valid name, and a name already in use fails with 500:
1 2 3 4 | |
Update an AsRun filter
PUT /api/asrun/filters/[FILTER]
Replaces an existing AsRun filter. The body is a complete filter object; it is stored as given, so any property left out is removed from the filter. The body may carry a different name, which renames the filter.
Request
| Parameter | Type | Description |
|---|---|---|
| FILTER | String (path) | Name of the filter to update |
1 2 3 4 5 6 7 8 9 | |
Response
The updated filter. If no filter of that name exists the response is 404:
1 2 3 4 | |
Delete an AsRun filter
DELETE /api/asrun/filters/[FILTER]
Deletes a saved AsRun filter.
Request
| Parameter | Type | Description |
|---|---|---|
| FILTER | String (path) | Filter name |
Response
If the filter exists, the removed filter is returned:
1 2 3 4 5 6 7 8 9 | |
If the filter does not exist the response is 404:
1 2 3 4 | |