Time Series

Time series data lets you import a CSV file and view its columns as charted channels in the Label Editor. Use Time range labels to mark areas of interest, such as events and anomalies, similarly to audio data annotation. This page explains the CSV format Encord expects, how to register time series files, and how to view and label them in the Label Editor. To upload time series files from your machine and set how channels are displayed using the SDK, see Time-series Data (SDK). Drawing a time range over robot telemetry synchronized with three camera views, then opening its attributes

Drawing a time range over robot telemetry synchronized with three camera views, then opening its attributes

Register Time Series Data

Choose how to bring your CSV files into Encord: register files from private cloud storage, sync a cloud folder, or upload local files to Encord storage.

Private Cloud Import

Register CSV files with the time_series top-level key in your upload JSON. This example registers accelerometer readings from a robot arm performing a pick-and-place task and configures the X-axis channel as a blue line.

Time series upload JSON

{
  "time_series": [
    {
      "objectUrl": "s3://my-bucket/robot-arm/pick-and-place/accelerometer.csv",
      "title": "Robot arm — pick-and-place accelerometer",
      "clientMetadata": {
        "robot_type": "robot_arm",
        "task": "pick_and_place"
      },
      "settings": {
        "channels": {
          "acc_x": {
            "label": "Acceleration X",
            "color": "#2563eb",
            "hidden": false,
            "style": "line",
            "lineWidth": 2
          }
        }
      }
    }
  ]
}

The settings object is optional. Channel keys match the CSV headers; channels without settings use the default appearance. Then register the JSON file through the existing data registration flow:

UI: Manual Data Registration
SDK: Import/Register Data

See Time Series Customization to configure channels during registration, update settings with the SDK, or change their appearance in the editor.

Cloud-Synced Folder

Use a Cloud-synced folder to register time series CSV files from a cloud storage path and pick up new files when the folder syncs.

Create a cloud integration with access to your files.
In Data > Files & Folders, select New folder > Cloud-synced folder.
Select the integration and enter the storage path containing your CSV files, then click Create.
Resync the folder manually when files change, or enable Automatically sync data for daily updates.

CSV files must have a text/csv or application/csv content type in cloud storage. To customize channels after registration, use the SDK or editor controls.

Encord Storage (UI and SDK)

Upload local CSV files to an Encord folder using either the UI or the SDK:

UI: In Data > Files & Folders, click Upload files, select a destination folder, and drag your CSV files into the Upload tab. Click Upload to finish. See Upload Local Data.
SDK: Call upload_time_series() on your destination StorageFolder. You can pass optional channel settings with the upload. See Time-series Data (SDK) for client setup and a complete example.

Upload a CSV to Encord storage

# folder is an authenticated StorageFolder from client.get_storage_folder(...).
file_id = folder.upload_time_series(
    file_path="/path/to/accelerometer.csv",
    title="Robot arm — pick-and-place accelerometer",
)

Time Series Column Structure

Encord supports CSV files for standalone time series data. Each file must contain a header row, one timestamp column, and at least one channel column. See Timestamp column for how Encord picks and interprets the timestamp column.

Example

time_ms,acc_x,acc_y,acc_z
0,0.12,0.02,0.98
100,0.18,0.03,1.01
200,0.15,0.01,0.99

This example uses millisecond timestamps, which work well for standalone time series files. If you pair the file with a video, use frame indices instead. See Align Time Series with Video.

Timestamp column

Encord picks the timestamp column as follows:

The timestamp column is the first column whose header is t, time, or timestamp, or starts with one of these followed by _ or - (for example time_ms or timestamp-utc). Matching is case-insensitive.
If no header matches, Encord uses the first column as the timestamp column.
Every other column is treated as a channel and plotted in the editor. Channel headers must be unique.
Empty, NaN, null, or otherwise non-numeric channel values are treated as gaps.
Rows without a valid timestamp are skipped.

Timestamp units

Encord infers the timestamp unit from the suffix of the timestamp column header:

Header suffix	Unit	Example header	Example values
`_ns`, `_nanosecond(s)`	Nanoseconds	`time_ns`	`0`, `33333333`
`_us`, `_microsecond(s)`	Microseconds	`time_us`	`0`, `33333`
`_ms`, `_millisecond(s)`	Milliseconds	`time_ms`	`0`, `100`, `200`
`_s`, `_sec`, `_second(s)`	Seconds	`time_s`	`0`, `1`, `2`
`_iso`	ISO 8601 date-time	`time_iso`	`2026-09-30T10:00:00.000Z`
No recognized suffix	Frame index (see below)	`frame`, `timestamp`	`0`, `1`, `2`

If the header has no recognized suffix, Encord looks at the values. Clock values such as 00:01:23.500 are read as elapsed time, and ISO 8601 date-times are read as ISO timestamps. Any other numeric values are treated as frame indices on the timeline.

Nanosecond, microsecond, millisecond, and second timestamps must be whole numbers. Rows with decimal values, such as 33.333 in a time_ms column or 0.5 in a time_s column, are skipped without an error. To keep sub-unit precision, use a smaller unit (for example time_us instead of time_ms) or use frame indices.

Unit-based timestamps (nanoseconds through ISO) are measured relative to the first valid row of the CSV. The first row always lines up with the start of the timeline, whatever its absolute value. ISO timestamps are read with millisecond precision.

Common Issues

Symptom	Likely cause	Fix
The chart drifts away from the video or does not line up with the frame cursor	The CSV uses unit-based timestamps (for example `time_ms`) in a Data Group with a video	Use a frame index column, as described in Align Time Series with Video
Rows or samples are missing from the chart	Decimal values in a `_ns`, `_us`, `_ms`, or `_s` timestamp column	Use whole numbers, a smaller unit, or frame indices
The chart is offset from the start of the video	The first CSV row is not at the start of the video	Remove leading rows, or use frame indices that start at the matching video frame
Timestamps are plotted as frames instead of time	The header has no recognized unit suffix, for example `Time (ms)`	Rename the header, for example to `time_ms`
A timestamp column is plotted as a channel	The timestamp header does not start with `t`, `time`, or `timestamp`, and it is not the first column	Move the timestamp column to the first position or rename it
The file fails to open with “Time series CSV channel headers must be unique”	Two channel columns share a header	Give every channel a unique header

Annotating Time Series Data

Add a Time range object to your Ontology, then open a time series task in the Label Editor.

Select the Time range class.
Drag across the chart to mark an interval.
Select the range to adjust its boundaries and fill in its attributes in the left sidebar.

Regions can be copied with CMD / CTRL + C and pasted with CMD / CTRL + V.

Open Visualization using the waveform icon next to the settings cog in the playback toolbar. Enable Show tooltip to inspect channel values while hovering over the chart.

Time Series in Data Groups

A Data Group layout can show a time series file in a layout tile tile, or in the shared timeline. The chart stays synchronized with the group’s frame navigation and displays the current frame cursor. Scroll to pan the chart. To zoom, hold Ctrl (Windows) or Command (macOS) while scrolling, or pinch on a trackpad. You can also create and edit time range labels directly in the tile.

Three robot camera views with joint telemetry in the shared timeline — Both layouts keep the camera views and telemetry synchronized as you scrub through the Data Group.

Three robot camera views beside separate joint position, gripper position, and joint torque chart tiles — Both layouts keep the camera views and telemetry synchronized as you scrub through the Data Group.

Aligning Time Series with Videos

When a Data Group contains timeseries and videos, index the time series by video frame rather than by time:

Make the frame column the first column of the CSV and give it a header without a unit suffix, such as frame.
Set each value to the video frame the sample belongs to, starting at 0 for the first video frame.

Frame index values are placed directly on the matching video frames, so the chart stays synchronized with the frame cursor. Values do not need to be whole numbers. A value of 1.5 sits halfway between frames 1 and 2, so data sampled faster than the video frame rate keeps its position. To convert timestamps to frame indices, multiply the time in seconds since the start of the video by the video frame rate:

frame = (sample_time_seconds - video_start_seconds) * video_fps

For example, 60 Hz sensor data paired with a 30 fps video produces two samples per video frame:

Frame-indexed time series for a 30 fps video

frame,acc_x,acc_y,acc_z
0,0.12,0.02,0.98
0.5,0.14,0.02,0.99
1,0.18,0.03,1.01
1.5,0.16,0.02,1.00
2,0.15,0.01,0.99

If the time series starts later than the video, start the frame column at the matching frame (for example 45 for a sample taken 1.5 seconds into a 30 fps video). Unit-based timestamps always start at the first row, so they cannot express this offset.

Time Series in Composite Scenes

Attach a time series CSV stream when you create and register a Composite Scene. For example, combine a LiDAR stream and a telemetry CSV:

Composite Scene with time series

from encord.beta.scene import SceneBuilder

scene = SceneBuilder()
scene.add_pcd_stream("lidar").add_pcd(
    uri="s3://my-bucket/robot-run/lidar/000000.pcd",
    timestamp=0,
)
scene.add_time_series_stream(
    "telemetry",
    uri="s3://my-bucket/robot-run/telemetry.csv",
)

# Use your authenticated StorageFolder and cloud integration.
scene_id = folder.upload_scene(
    scene=scene,
    title="Robot run with telemetry",
    integration_id="<integration_id>",
)

Use a Scene layout to select its numeric channels and place them in the timeline or separate chart tiles alongside camera and 3D views.

Time Series in MCAP Files

MCAP files can contain camera, 3D, and numeric telemetry channels in one recording. Use a Scene layout to select numeric sub-channels and place them in the timeline or separate chart tiles. The example below shows a robot camera view alongside forward and turning velocity charts at the same point in an MCAP recording. See MCAP Support for registration and Time Series in Scenes for the layout and labeling workflow. MCAP robot camera view with synchronized forward and turning velocity charts

Overview

LiDAR, Radar and Sensor Data

Time Series Data

Visual Data

Audio Data

Text, HTML, and PDFs

DICOM and NIFTI

Multimodal

Geospatial Data

Register Time Series Data

Private Cloud Import

Cloud-Synced Folder

Encord Storage (UI and SDK)

Time Series Column Structure

Timestamp column

Timestamp units

Common Issues

Annotating Time Series Data

Time Series in Data Groups

Aligning Time Series with Videos

Time Series in Composite Scenes

Time Series in MCAP Files

​Register Time Series Data

​Private Cloud Import

​Cloud-Synced Folder

​Encord Storage (UI and SDK)

​Time Series Column Structure

​Timestamp column

​Timestamp units

​Common Issues

​Annotating Time Series Data

​Time Series in Data Groups

​Aligning Time Series with Videos

​Time Series in Composite Scenes

​Time Series in MCAP Files

Register Time Series Data

Private Cloud Import

Cloud-Synced Folder

Encord Storage (UI and SDK)

Time Series Column Structure

Timestamp column

Timestamp units

Common Issues

Annotating Time Series Data

Time Series in Data Groups

Aligning Time Series with Videos

Time Series in Composite Scenes

Time Series in MCAP Files