> For the complete documentation index, see [llms.txt](https://docs.eyepop.ai/developer-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eyepop.ai/developer-documentation/platform/response-format/temporal-attributes.md).

# Temporal Attributes

How a prediction says when — timestamp, duration and captured\_at, and which to use for what

A prediction says *when* as well as *where*. There are two different clocks behind that: the **media's own timeline**, which starts at zero and counts through the video, and the **real time** a camera captured a frame. They answer different questions, and mixing them up is the most common mistake when correlating predictions with anything else.

All times are integers in **nanoseconds**: 1 second is `1000000000`.

<figure><img src="https://1956543008-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2tRktyRCGgE1tPlAfT4h%2Fuploads%2Fgit-blob-98a929e0ab51d30819bdbfa9a7c51ae1dee96225%2Fresponse-format-times.svg?alt=media" alt="A timeline from 0 to 10 seconds. Each live prediction covers one frame, starting at its timestamp and lasting its duration. Above it, the camera clock gives captured_at from 09:30:02 on; before that it is not known yet. A motion runs from begin_timestamp at 1 s to finished_timestamp at 7 s. A track runs from started_at at 2 s to ended_at at 6 s; its start is reported on the prediction at 3 s and its end later, on the prediction at 8 s. A selected prediction carries the timestamp of the live 4 s prediction but arrives after the live 8 s prediction, so the arrival order is 0 to 8 s, then 4 s, then 9 s."><figcaption><p>Every time a prediction can carry, on one timeline.</p></figcaption></figure>

### Position in the media: `timestamp`

`timestamp` is where the frame sits on the media's timeline, counted from its start. A video recorded at 24 frames per second produces predictions like these:

```json
{ "timestamp": 0,          "seconds": 0,           "duration": 41666666 }
{ "timestamp": 41666667,   "seconds": 0.041666667, "duration": 41666666 }
{ "timestamp": 83333333,   "seconds": 0.083333333, "duration": 41666666 }
```

* A single image has one moment, so its `timestamp` is `0`.
* A video file's timestamps are its playback positions, the same a video player shows. The frame at 0:12 has a `timestamp` of `12000000000`.
* A live stream's timestamps count through the stream as EyePop receives it. They order the frames and measure the time between them, but they say nothing about the time of day.

`timestamp` is always present. It is the key to order a source's predictions by, and to find the frame a prediction belongs to when you go back to the video.

### Convenience: `seconds`

`seconds` is the same position as `timestamp`, in seconds, for display and logging. Compare and store `timestamp`: `seconds` is a floating-point copy and can differ from it in the last digits.

### Length of the frame: `duration`

`duration` is how long the frame stands for on the timeline: the time until the next processed frame. At 24 frames per second that is `41666666` nanoseconds. A single image has no `duration`.

With [`fps`](https://docs.eyepop.ai/developer-documentation/platform/sources-and-options/options/frame-rate.md) set lower than the video's own rate, the Pop skips frames, and each frame it processes stands for the frames skipped after it. The same 24 fps video at `fps="5/1"`:

```json
{ "timestamp": 0,         "duration": 200000000 }
{ "timestamp": 208333333, "duration": 200000000 }
{ "timestamp": 416666667, "duration": 200000000 }
```

The `timestamp` values stay on the video's own frames, about 0.2 seconds apart, and `duration` is the 0.2 seconds each one covers.

### Real time of capture: `captured_at`

`captured_at` is the moment a camera captured the frame, on the camera's own clock, in nanoseconds since the Unix epoch (1970-01-01 UTC). It appears only on frames from a camera that provides its clock, such as an RTSP camera that sends RTCP sender reports:

```json
{ "timestamp": 75000000000, "seconds": 75, "duration": 33333333, "captured_at": 1793394780812274000 }
```

This frame is 75 seconds into the stream, and the camera captured it at 2026-10-30 21:13:00.812 UTC.

Unlike `timestamp`, `captured_at` can be compared across sources and against anything outside EyePop: another camera, a door sensor, a point-of-sale log. Network and buffering delay between the camera and EyePop vary, and `captured_at` is unaffected by both.

`captured_at` is **left out, never guessed**, when the capture time is not known: on a file, on a camera without a usable clock, and for the first moments of a stream, before the camera's first clock reference arrives. [Private Cameras](https://docs.eyepop.ai/developer-documentation/deploying/cloud/private-cameras.md#capture-time-on-a-relayed-camera) describes when a camera provides it.

### Which time to use

| To…                                                           | Use                                      |
| ------------------------------------------------------------- | ---------------------------------------- |
| Order the predictions of one source                           | `timestamp`                              |
| Find the frame in a video file, or cut a clip around it       | `timestamp`                              |
| Show a position to a person                                   | `seconds`                                |
| Measure how long something lasted in the media                | the difference of two `timestamp` values |
| Match frames from different cameras, or with sensors and logs | `captured_at`                            |
| Know the time of day a live frame was taken                   | `captured_at`                            |

### Times inside a prediction

Some results carry times of their own. They are on the same timeline as `timestamp`:

* A [track event](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions/tracks-and-selected-predictions.md#track-events) says when a tracked object was first and last seen, as `started_at` and `ended_at`.
* A [motion](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions.md#motion) says when motion began, as `begin_timestamp`.

A [selected prediction](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions/tracks-and-selected-predictions.md#selected-predictions) reports about a frame from the past. Its `timestamp`, `duration` and `captured_at` are that frame's, so it arrives later than predictions with a later `timestamp`.

### Example: print the times of a prediction

{% tabs %}
{% tab title="Python" %}

```python
from datetime import datetime, timezone

def describe_time(prediction):
    seconds = prediction["timestamp"] / 1e9
    text = f"{int(seconds // 60)}:{seconds % 60:06.3f} into the media"
    if "captured_at" in prediction:
        captured = datetime.fromtimestamp(prediction["captured_at"] / 1e9, tz=timezone.utc)
        text += f", captured {captured.isoformat()}"
    return text

print(describe_time({"timestamp": 75000000000, "captured_at": 1793394780812274000}))
# 1:15.000 into the media, captured 2026-10-30T21:13:00.812274+00:00
```

{% endtab %}

{% tab title="Node" %}

```typescript
import { Prediction } from '@eyepop.ai/eyepop'

function describeTime(prediction: Prediction): string {
    const seconds = (prediction.timestamp ?? 0) / 1e9
    let text = `${Math.floor(seconds / 60)}:${(seconds % 60).toFixed(3).padStart(6, '0')} into the media`
    if (prediction.captured_at !== undefined) {
        text += `, captured ${new Date(prediction.captured_at / 1e6).toISOString()}`
    }
    return text
}

console.log(describeTime({ source_width: 1280, source_height: 720, timestamp: 75000000000, captured_at: 1793394780812274000 }))
// 1:15.000 into the media, captured 2026-10-30T21:13:00.812Z
```

{% endtab %}
{% endtabs %}

JavaScript numbers hold integers exactly only up to 2<sup>53</sup>, about 9 × 10<sup>15</sup>. A `captured_at` is about 1.8 × 10<sup>18</sup>, so in JavaScript it is precise to roughly a quarter of a microsecond, far finer than any frame rate.

### Next steps

* [Predictions](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions.md) — every field of a prediction
* [Tracks and Selected Predictions](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions/tracks-and-selected-predictions.md) — times that span many frames
