Skip to content

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
[
    {
        "timestamp": "2024-02-28 21:05:39.53",
        "level": "TRACE",
        "category": "AsRun",
        "message": "TAKE_IN",
        "meta": {
            "show": "5e1b0b9a8f1c2d0012a4b7c1",
            "page": "Opening",
            "profile": "5e1b0b9a8f1c2d0012a4b7f3",
            "channel": "5e1b0b9a8f1c2d0012a4b801"
        },
        "index": 0
    }
]

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
[
    {
        "page": 0,
        "start": "2024-02-28 21:05:39.53",
        "ref": 0
    },
    {
        "page": 1,
        "start": "2024-02-28 22:14:02.11",
        "ref": 48213
    }
]

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
{
    "from": "20:00",
    "to": "23:00",
    "action": "TAKE_IN",
    "show": "5e1b0b9a8f1c2d0012a4b7c1",
    "profile": "5e1b0b9a8f1c2d0012a4b7f3",
    "channel": "5e1b0b9a8f1c2d0012a4b801"
}

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
[
    {
        "time": "2024-02-28 21:05:39.53",
        "show": "News/EveningNews",
        "pageName": "Opening",
        "action": "In",
        "profile": "Main",
        "channel": "Program"
    },
    {
        "time": "2024-02-28 21:10:12.11",
        "show": "News/EveningNews",
        "pageName": "Opening",
        "action": "Out",
        "profile": "Main",
        "channel": "Program"
    }
]

CSV report example

The CSV file is UTF-8 with a byte order mark and CRLF line endings.

1
2
3
Time,Show,Page Name,Action,Profile,Channel
2024-02-28 21:05:39.53,News/EveningNews,Opening,In,Main,Program
2024-02-28 21:10:12.11,News/EveningNews,Opening,Out,Main,Program

Errors

If the saved filter does not exist the request fails with 500:

1
2
3
4
{
    "status": "ERROR",
    "error": "Filter 'primetime' was not found"
}

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
[
    {
        "name": "PrimeTime",
        "scheduled": true,
        "from": "20:00",
        "to": "23:00",
        "action": "TAKE_IN",
        "show": "5e1b0b9a8f1c2d0012a4b7c1",
        "profile": "5e1b0b9a8f1c2d0012a4b7f3",
        "channel": "5e1b0b9a8f1c2d0012a4b801"
    }
]

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
{
    "status": "ERROR",
    "error": "Not found"
}

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
{
    "name": "PrimeTime",
    "scheduled": true,
    "from": "20:00",
    "to": "23:00",
    "action": "TAKE_IN",
    "show": "5e1b0b9a8f1c2d0012a4b7c1",
    "profile": "5e1b0b9a8f1c2d0012a4b7f3",
    "channel": "5e1b0b9a8f1c2d0012a4b801"
}

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
{
    "status": "ERROR",
    "error": "Duplicate filter: PrimeTime"
}

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
{
    "name": "PrimeTime",
    "scheduled": true,
    "from": "19:30",
    "to": "23:00",
    "show": "5e1b0b9a8f1c2d0012a4b7c1",
    "profile": "5e1b0b9a8f1c2d0012a4b7f3",
    "channel": "5e1b0b9a8f1c2d0012a4b801"
}

Response

The updated filter. If no filter of that name exists the response is 404:

1
2
3
4
{
    "status": "ERROR",
    "error": "Not found"
}

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
{
    "name": "PrimeTime",
    "scheduled": true,
    "from": "19:30",
    "to": "23:00",
    "show": "5e1b0b9a8f1c2d0012a4b7c1",
    "profile": "5e1b0b9a8f1c2d0012a4b7f3",
    "channel": "5e1b0b9a8f1c2d0012a4b801"
}

If the filter does not exist the response is 404:

1
2
3
4
{
    "status": "ERROR",
    "error": "Not found"
}