Get Data Series

Request

To retrieve time-series data for one or more Variables, make a POST request to the following URL:

HTTP Method	URL
POST	`https://industrial.api.ubidots.com/api/v2.0/data/series/`

Query Parameters

Parameter	Type	Default	Description
results_format	String	"tabular"	Format of each data point in the response. Options: `tabular` (arrays), `object` (named-key dicts)
results_data	Boolean	true	When `false`, skips fetching time-series data and returns empty `results` arrays. Useful for validating variable existence and permissions without the cost of a data query
storage	String	—	Storage tier to query. Options: `hot`, `cold`, `auto`. Optional

Body Parameters

Parameter	Type	Required?	Description
start	Integer	Yes	Start of the time range as a timestamp in milliseconds (epoch)
end	Integer	Yes	End of the time range as a timestamp in milliseconds (epoch)
decimalPlaces	Integer	No	Number of decimal places for values (0–16). Defaults to the account setting
columns	String Array	No	Columns to include. Options: `timestamp`, `value`, `context`, `created_at`
variables	Object Array	Yes	List of variable references to query. Minimum 1 item. See Variables Array

Header

Parameter	Required?	Description
X-Auth-Token	Yes	Authentication Token of account

$ curl -X POST 'https://industrial.api.ubidots.com/api/v2.0/data/series/' \
 -H 'Content-Type: application/json' \
 -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73' \
 -d '{
    "start": 1700000000000,
    "end": 1700086400000,
    "decimalPlaces": 6,
    "columns": ["timestamp", "value", "context", "created_at"],
    "variables": [
        {
            "variable": "64a1b2c3d4e5f6a7b8c9d0e1"
        },
        {
            "variable": "~temperature",
            "device": "~my-device"
        }
    ]
}'

{
    "start": 1700000000000,
    "end": 1700086400000,
    "results": [
        {
            "device": {
                "id": "6e309da44fc8455a9cceb5aa",
                "label": "first-device",
                "name": "First Device",
                "createdAt": "2023-11-01T00:00:00.000000Z"
            },
            "variable": {
                "id": "64a1b2c3d4e5f6a7b8c9d0e1",
                "label": "temperature",
                "name": "Temperature",
                "createdAt": "2023-11-01T00:00:00.000000Z"
            },
            "code": 200,
            "columns": ["timestamp", "value", "context", "created_at"],
            "results": [
                [1700000100000, 23.5, {}, 1700000100001]
            ]
        }
    ]
}

{
    "start": 1700000000000,
    "end": 1700086400000,
    "results": [
        {
            "variable": {
                "id": "nonexistent_id"
            },
            "code": 404,
            "message": "Variable or Device not found"
        }
    ]
}

{
    "start": 1700000000000,
    "end": 1700086400000,
    "results": [
        {
            "variable": {
                "id": "64a1b2c3d4e5f6a7b8c9d0e1"
            },
            "code": 403,
            "message": "No permissions on this variable"
        }
    ]
}

{
    "detail": "Authentication credentials were not provided."
}

Response

Returns an object with start, end, and results. Each item in results corresponds to one requested variable and contains its own code, allowing a single request to partially succeed — some variables may return 200 while others return 403 or 404.

Successful entry fields:

Field	Description
device	Object with `id`, `label`, `name`, and `createdAt` of the Device
variable	Object with `id`, `label`, `name`, and `createdAt` of the Variable
code	`200` on success
columns	The columns included in each data point (omitted when `results_format=object`)
results	Array of data points. Empty array when `results_data=false`

Data point format:

results_format=tabular (default) — each data point is an array matching the order of columns. Example: [1700000100000, 23.5, {}, 1700000100001]
results_format=object — each data point is an object with named keys. Example: {"timestamp": 1700000100000, "value": 23.5, "context": {}, "created_at": 1700000100001}. The columns field is omitted from the entry.

When results_data=false: The response structure is identical but all results arrays are empty. Use this to validate variable existence and permissions without fetching historical data.

Error entries (per variable):

Code	Cause
404	Variable or Device not found
403	No permissions on the variable