Process API
Check the state of an Astra instance, monitor system resources, read logs and restart the instance. See How to call API methods for authentication and custom control paths.
Get status
Section titled “Get status”Read the version, uptime, license and detected hardware. The response example shows the main fields; hardware fields are described below.
/control/Request body
{ "cmd": "status" }Response excerptHTTP 200
{ "status": "ok", "version": "Astra 260918 (commit:c109858f)", "uptime": 3600, "hostname": "streamer-1", "cpu_power_save": false, "license": { "id": "ABCDEF", "type": 2, "expire": 1790000000 }}| Field | Description |
|---|---|
status | "ok" |
version | Astra build version |
uptime | Process uptime in seconds. Restart does not reset it |
hostname | The instance_name setting, or the system host name |
cpu_power_save | true when the CPU frequency scaling policy holds the CPU below the clock it is capable of; read at start and once a minute |
license | License details. Fields depend on the license state; see License fields |
dvb_list | Detected DVB frontends. Omitted when none are found and while the start-up probe runs |
modulator_list | Detected modulators. Omitted when none are found and while the start-up probe runs |
if_list | Names of network interfaces that are up, for example ["lo", "eth0"] |
net_list | Details of those network interfaces. Both network lists are omitted when no interface is up |
DVB frontends
Section titled “DVB frontends”Each dvb_list item describes one frontend. Astra probes the frontends in the background when it starts; restart Astra or call List DVB devices with reset to refresh this list after hardware changes.
| Field | Description |
|---|---|
adapter, device | Numeric indexes in /dev/dvb/adapterN/frontendM |
busy | true while an adapter configuration of this instance uses the frontend, or when it was open for writing as the list was built. Omitted if it could not be opened |
type | Frontend class: S, C, T or ATSC, when detected |
frontend | Driver-reported frontend name, when detected |
mac | Adapter MAC address, when available |
error | Probe error, such as Permission denied |
Modulators
Section titled “Modulators”Each modulator_list item describes one modulator device. kind, adapter and device are the settings of the output that drives it.
| Field | Description |
|---|---|
kind | Output type: resi for DigitalDevices (/dev/dvb/adapterN/modM), tbs for TBS (/dev/tbsmodN/modM), it950x for HiDes (/dev/usb-it950xN) |
adapter, device | Numeric indexes in the device path. device is always 0 for it950x, whose output takes adapter only |
busy | true while an output of this instance uses the device, or when it was open for writing as the list was built |
Network interfaces
Section titled “Network interfaces”Each net_list item describes one interface that is up.
| Field | Description |
|---|---|
name | Interface name, for example eth0 |
up | Always true for interfaces in this list |
loopback, running, broadcast, multicast | Present as true when the corresponding interface flag is set |
flags | Numeric interface flags |
index | Numeric interface index |
mac | Link-layer address, when available |
ipv4 | IPv4 addresses, for example ["192.168.1.10"], when available |
System status
Section titled “System status”Read CPU, memory and uptime statistics. Set t to 0 for the latest sample, or omit it for the last interval report. Also served as GET /api/system-status.
/control/Request body
{ "cmd": "system-status", "t": 0}ResponseHTTP 200
{ "timestamp": 1758268800, "instance": "streamer-1", "la1": 45, "la5": 40, "la15": 38, "app_threads": 12, "sys_cpu_usage": 12, "app_cpu_usage": 3, "sys_mem_usage": 31, "app_mem_usage": 1, "app_mem_kb": 163184, "sys_uptime": 14400, "app_uptime": 60}Samples update every 10 seconds. Interval reports average thread count, CPU and memory usage over 60 seconds by default, configured by tsdb_interval. Load averages and uptimes use the last sample. Values are zero until the first sample or report is ready.
| Field | Description |
|---|---|
timestamp | Unix time: report creation time for t=1, latest sample time for t=0, 0 before the first sample |
instance | The instance_name setting. Omitted when not set |
la1, la5, la15 | Load averages over 1, 5 and 15 minutes, multiplied by 100 and truncated. For example, 45 means 0.45 |
app_threads | Number of process threads |
sys_cpu_usage | Total system CPU usage, 0 to 100% across all CPUs |
app_cpu_usage | Process CPU usage as a percentage of one CPU. Can exceed 100% on a multi-core host |
sys_mem_usage | Percentage of total system memory that is not available |
app_mem_usage | Process resident memory as a percentage of total system memory |
app_mem_kb | Process resident memory in KiB |
sys_uptime | Time since system boot, in minutes |
app_uptime | Time since the process started, in minutes. Does not reset after Restart |
tnumberOptional- 0 for the latest sample; 1 for the last interval report. Default: 1.
With POST /control/, put t in the JSON body; with GET /api/system-status, pass it in the query. A decimal numeric string is read as its number, any other value counts as 1. A numeric t other than 0 or 1 returns HTTP 200 with an error:
{ "system-status": "er", "error": "not implemented" }Monitoring
Section titled “Monitoring”Read the latest one-second statistics of every stream and adapter, and the latest system sample, in one request. Also served as GET /api/monitoring. The built-in web interface polls this method once per second for its dashboard.
/control/Request body
{ "cmd": "monitoring" }ResponseHTTP 200
{ "timestamp": 1758268800, "instance": "streamer-1", "system": { "timestamp": 1758268795, "la1": 45, "la5": 40, "la15": 38, "app_threads": 12, "sys_cpu_usage": 12, "app_cpu_usage": 3, "sys_mem_usage": 31, "app_mem_usage": 1, "app_mem_kb": 163184, "sys_uptime": 14400, "app_uptime": 60 }, "streams": [ { "id": "a001", "name": "Channel 1", "input_id": 1, "sessions": 3, "inputs": [ { "input_id": 1, "timestamp": 1758268800, "onair": true, "bitrate": 4210, "packets": 2799, "pes_packets": 75, "pes_error": 0, "sc_error": 0, "cc_error": 0, "sync_error": 0, "video_count": 1, "audio_count": 1 }, { "input_id": 2, "timestamp": 0, "onair": false, "bitrate": 0, "packets": 0, "pes_packets": 0, "pes_error": 0, "sc_error": 0, "cc_error": 0, "sync_error": 0, "video_count": 0, "audio_count": 0 } ] }, { "id": "m001", "name": "Multiplex 1", "input_id": 0, "sessions": 0, "inputs": [ { "input_id": 0, "timestamp": 1758268800, "onair": true, "bitrate": 38000, "packets": 0, "pes_packets": 0, "pes_error": 0, "sc_error": 0, "cc_error": 0, "sync_error": 0, "video_count": 0, "audio_count": 0 }, { "input_id": 1, "timestamp": 1758268800, "onair": true, "bitrate": 41000, "packets": 27260, "pes_packets": 820, "pes_error": 0, "sc_error": 0, "cc_error": 0, "sync_error": 0, "video_count": 9, "audio_count": 14 } ] } ], "adapters": [ { "id": "a002", "name": "Astra 19.2E", "timestamp": 1758268800, "lock": true, "status": 31, "signal": 78, "signal_db": -4520, "snr": 62, "snr_db": 1380, "ber": 0, "unc": 0, "bitrate": 41000 }, { "id": "a006", "name": "SAT>IP 1", "timestamp": 1758268800, "lock": true, "status": 0, "signal": 0, "signal_db": 0, "snr": 0, "snr_db": 0, "ber": 0, "unc": 0, "bitrate": 38500 } ]}The request takes no parameters. All values of a reply are read at the same moment. Stream and adapter samples are refreshed every second, the system sample every 10 seconds. Streams and adapters with no_event set collect no statistics and are absent.
| Field | Description |
|---|---|
timestamp | Current Unix time |
instance | The instance_name setting. Omitted when not set |
system | The latest system sample: the fields of System status with t set to 0, without instance; its timestamp is the time of that sample. Every value is 0 until the first sample |
streams | Running streams, see Stream statistics |
adapters | Running adapters, see Adapter statistics |
Stream statistics
Section titled “Stream statistics”Each streams item is an enabled SPTS or MPTS stream with an id. A stream that works on demand is listed while no client is connected too, with no inputs.
| Field | Description |
|---|---|
id | Stream identifier |
name | Stream name |
input_id | The source input, whose values Get stream status reports for the stream. 0 while no input is the source, and for an MPTS stream, whose source is input 0, the multiplex output |
sessions | Number of client sessions on the stream, counted when the last monitoring interval closed (the tsdb_interval setting) |
inputs | The running inputs in ascending input_id order: an input is listed from its start until it is stopped. Empty while no input runs |
Each inputs item is the analyzer sample of one input for the last second. The counters are raw counts, not the percentages of Get stream status.
| Field | Description |
|---|---|
input_id | Input number: the one-based position of the input in the stream’s input list. 0 is the multiplex output of an MPTS stream |
timestamp | Unix time of the sample. 0 when the input has started and has no sample yet |
onair | The analyzer’s verdict: false when the payload bitrate is under the expected minimum, a video or audio PID is scrambled or had more than 2 PES errors, or the CC error limit is reached |
bitrate | Kbit/s |
packets | TS packets received |
pes_packets | Video and audio packets that start a PES packet |
pes_error | Packets counted in pes_packets whose payload does not begin with a PES header |
sc_error | Scrambled TS packets |
cc_error | Continuity counter errors |
sync_error | Always 0 |
video_count, audio_count | Number of video and audio PIDs |
An input with no_analyze set has no analyzer: it is listed with timestamp 0 and every value 0.
For an MPTS stream input 0 is the multiplex output and the source of the stream: onair is true, bitrate is the Kbit/s the multiplexer emitted in the last second, and every other value is 0. Inputs 1 and up are the multiplexed inputs with the values of their analyzers.
Adapter statistics
Section titled “Adapter statistics”Each adapters item is a running adapter with an id: an adapter with a frontend type, a SAT>IP adapter or a virtual adapter (see Adapter configuration).
| Field | Description |
|---|---|
id | Adapter identifier |
name | The adapter name, or its id when the name is not set |
timestamp | Unix time of the sample. 0 until the first sample |
lock | true if the frontend reported lock. For a SAT>IP or virtual adapter: true while it is on air |
status | Frontend status bits: 0x01 signal, 0x02 carrier, 0x04 FEC inner coding, 0x08 sync, 0x10 lock, 0x20 timed out, 0x40 reinitialized. 0 (and lock false) in the second in which the adapter’s watchdog stopped it |
signal, snr | Signal level and signal to noise ratio as reported by the driver: percent with the DVB API v5 status, raw driver units with the dvbapi3 option |
signal_db, snr_db | Decibels multiplied by 100. 0 with the dvbapi3 option |
ber, unc | Bit errors and uncorrected blocks as reported by the driver |
bitrate | Kbit/s received over the last second |
A SAT>IP or virtual adapter has no frontend: lock is its on-air state, bitrate the rate of its transport, and status and the signal fields are 0. A SAT>IP adapter and an address-based adapter are on air when packets arrived in the last second; a CI adapter when the stream passed through the CAM in the last second and the CAM is ready.
A scan session adds no item: a scan of a configured adapter, such as dvb://a002 or a dvb object naming the adapter in id, reads that adapter’s own item, and an adapter a scan tunes from its own options without an id collects no statistics.
Version
Section titled “Version”Read the Astra build version.
/control/Request body
{ "cmd": "version" }ResponseHTTP 200
{ "version": "Astra 260918 (commit:c109858f)" }The version contains the build date and commit.
Read the most recent log entries, oldest first. Astra keeps up to 2000 entries in memory, separately from the log file.
/control/Request body
{ "cmd": "log" }ResponseHTTP 200
{ "log": [ { "level": "INFO", "time": 1758268800, "message": "[main] Starting Astra 260918 (commit:c109858f)" }, { "level": "ERROR", "time": 1758268801, "message": "[main] Authentication failed. Login:admin IP:192.168.1.10" } ], "last_id": 1043}| Field | Description |
|---|---|
log | Log entries, oldest first |
log[].level | INFO, WARN, ERROR or DEBUG. Debug entries require debug logging |
log[].time | Unix time when the entry was recorded |
log[].message | Message without the timestamp and level prefix |
last_id | ID to use in the next request to read newer entries |
Read new log entries
Section titled “Read new log entries”Pass last_id from the previous response to read only newer entries:
/control/Request body
{ "cmd": "log", "last_id": 1043}ResponseHTTP 200
{ "log": [ { "level": "INFO", "time": 1758268802, "message": "[main] Reloading configuration" } ], "last_id": 1044}Use 1044 in the next request. If there are no new entries, the response is {"log": []} without last_id; keep the previous value. Read frequently enough to stay within the 2000-entry archive.
last_idnumberOptional- Return entries recorded after this ID. Omit to read the entire archive.
With POST /control/, put last_id in the JSON body.
Restart
Section titled “Restart”Reload the configuration file and restart streams, adapters and servers.
/control/Request body
{ "cmd": "restart" }ResponseHTTP 200
{ "restart": "ok" }The restart begins one second after the response. Streaming and API access are briefly interrupted, and WebSocket clients must reconnect.
For authentication and HTTP errors, see API replies.