HTTP read task

Learn how to acquire data from HTTP endpoints with Synnax.

This task follows the standard task lifecycle.

Task configuration reference

Table

Parameter	Type	Required	Default	Description
`device`	string	Yes	-	Key of the HTTP server device
`rate`	number	No	`1`	Polling rate (Hz)
`endpoints`	array	Yes	-	List of endpoint configurations

Endpoint configuration reference

Each endpoint defines an HTTP request to poll and a set of fields to extract from its JSON response.

Table

Parameter	Type	Required	Default	Description
`method`	string	No	`"GET"`	HTTP method
`path`	string	Yes	-	URL path relative to the device base URL (e.g., `/api/v1/data`)
`headers`	array	No	-	Additional request headers as `{name, value}` pairs
`query_params`	array	No	-	Query parameters as `{parameter, value}` pairs
`body`	string	No	-	Request body (for POST or other methods that accept a body)
`index`	string	No	-	Key of the field whose channel indexes the others. Empty stamps samples on arrival
`fields`	array	Yes	-	Fields to extract from the response

Field extraction reference

Fields define how to extract values from a JSON response body using JSON Pointers (RFC 6901). Each field maps a location in the response to a Synnax channel.

For example, given this response:

{ "temperature": 23.5, "sensors": { "pressure": 101.3 } }

A pointer of /temperature extracts 23.5, and /sensors/pressure extracts 101.3.

Table

Parameter	Type	Required	Default	Description
`pointer`	string	Yes	-	JSON Pointer path to the value (e.g., `/temperature`)
`channel`	number	Yes	-	Synnax channel key to write the extracted value to
`data_type`	string	No	`"float64"`	Data type of the channel
`name`	string	No	-	Human-readable name for the field
`disabled`	boolean	No	`false`	Excludes the field from polling
`time_format`	string	No	-	Timestamp format (required when the channel data type is `TIMESTAMP`)
`enum_values`	array	No	-	String-to-number mapping for enum fields (e.g., `[{"label": "OFF", "value": 0}, {"label": "ON", "value": 1}]`)

Enum Values

When the HTTP response contains string values that represent discrete states, use enum_values to map them to numbers. The Driver converts matching strings to their numeric equivalents before writing to the channel.

http.ReadField(
    pointer="/status",
    channel=status_ch.key,
    data_type="float64",
    enum_values=[{"label": "OFF", "value": 0}, {"label": "ON", "value": 1}, {"label": "ERROR", "value": 2}],
)

If the response value does not match any key in the map, the Driver reports an error.

Timestamp handling

By default, the Driver automatically generates timestamps for each poll cycle using software timing. If your HTTP response includes a timestamp field, you can extract it directly by setting time_format on a field whose channel data type is TIMESTAMP.

Supported Timestamp Formats

Table

Format	Description	Example
`iso8601`	ISO 8601 date-time string	`"2024-01-15T10:30:00.000Z"`
`unix_sec`	Seconds since Unix epoch	`1705312200`
`unix_ms`	Milliseconds since Unix epoch	`1705312200000`
`unix_us`	Microseconds since Unix epoch	`1705312200000000`
`unix_ns`	Nanoseconds since Unix epoch	`1705312200000000000`

Software vs. Hardware Timing

Software timing (default): The Driver generates a timestamp at each poll cycle. All fields that share the same index channel are written atomically. No time_format is needed on any field.

Hardware timing: If your response includes a timestamp, create a TIMESTAMP channel as the index and add a field that extracts it with a time_format. Other fields using that index channel will be grouped with the extracted timestamp.

How-to

Console

Python

Configure and run task

import synnax as sy
from synnax import http

client = sy.Synnax()

# Retrieve the HTTP device
dev = client.devices.retrieve(name="My HTTP Server")

# Create an index channel for timestamps
http_time = client.channels.create(
    name="http_time",
    is_index=True,
    data_type=sy.DataType.TIMESTAMP,
    retrieve_if_name_exists=True,
)

# Create data channels
temperature = client.channels.create(
    name="http_temperature",
    index=http_time.key,
    data_type=sy.DataType.FLOAT64,
    retrieve_if_name_exists=True,
)

pressure = client.channels.create(
    name="http_pressure",
    index=http_time.key,
    data_type=sy.DataType.FLOAT64,
    retrieve_if_name_exists=True,
)

# Create the read task
task = http.ReadTask(
    name="HTTP Read Task",
    device=dev.key,
    rate=1,  # Poll at 1 Hz
    endpoints=[
        http.ReadEndpoint(
            method="GET",
            path="/api/v1/data",
            fields=[
                http.ReadField(
                    pointer="/temperature",
                    channel=temperature.key,
                    data_type="float64",
                    name="Temperature",
                ),
                http.ReadField(
                    pointer="/pressure",
                    channel=pressure.key,
                    data_type="float64",
                    name="Pressure",
                ),
            ],
        ),
    ],
)

# Configure the task with Synnax
client.tasks.configure(task)

# Start task and read data
with task.run():
    with client.open_streamer(
        ["http_temperature", "http_pressure"]
    ) as streamer:
        for _ in range(10):
            frame = streamer.read()
            print(frame)

Poll multiple endpoints

import synnax as sy
from synnax import http

client = sy.Synnax()
dev = client.devices.retrieve(name="My HTTP Server")

http_time = client.channels.create(
    name="http_time",
    is_index=True,
    data_type=sy.DataType.TIMESTAMP,
    retrieve_if_name_exists=True,
)

temperature = client.channels.create(
    name="http_temperature",
    index=http_time.key,
    data_type=sy.DataType.FLOAT64,
    retrieve_if_name_exists=True,
)

uptime = client.channels.create(
    name="http_uptime",
    index=http_time.key,
    data_type=sy.DataType.FLOAT64,
    retrieve_if_name_exists=True,
)

task = http.ReadTask(
    name="Multi-Endpoint Read",
    device=dev.key,
    rate=1,
    endpoints=[
        http.ReadEndpoint(
            method="GET",
            path="/api/v1/data",
            fields=[
                http.ReadField(
                    pointer="/temperature",
                    channel=temperature.key,
                    data_type="float64",
                ),
            ],
        ),
        http.ReadEndpoint(
            method="GET",
            path="/api/v1/status",
            fields=[
                http.ReadField(
                    pointer="/uptime",
                    channel=uptime.key,
                    data_type="float64",
                ),
            ],
        ),
    ],
)

client.tasks.configure(task)

Use enum values

import synnax as sy
from synnax import http

client = sy.Synnax()
dev = client.devices.retrieve(name="My HTTP Server")

http_time = client.channels.create(
    name="http_time",
    is_index=True,
    data_type=sy.DataType.TIMESTAMP,
    retrieve_if_name_exists=True,
)

power = client.channels.create(
    name="http_power",
    index=http_time.key,
    data_type=sy.DataType.FLOAT64,
    retrieve_if_name_exists=True,
)

task = http.ReadTask(
    name="Enum Read",
    device=dev.key,
    rate=1,
    endpoints=[
        http.ReadEndpoint(
            method="GET",
            path="/api/v1/device",
            fields=[
                http.ReadField(
                    pointer="/power",
                    channel=power.key,
                    data_type="float64",
                    enum_values=[
                      {"label": "OFF", "value": 0},
                      {"label": "ON", "value": 1},
                    ],
                ),
            ],
        ),
    ],
)

client.tasks.configure(task)

Connect to a server

Write task