Stream or query packets for your organization.

Required Scope: read-packets

Overview

This endpoint acts as a data stream. Use the Continuation-Token to track your consumer's position in the stream and ingest incrementally. Packets are returned in ascending order based on when they were detected by Hubble Network.

Pagination and Streaming

Use the Continuation-Token to capture new packets incrementally. If provided, all other query parameters are ignored, as the token persists the initial query's configuration.

Response Headers

• Continuation-Token: an opaque cursor for your position in the stream. The max page size is 1,000 packets.
  • If you supplied an end time, an empty string indicates you have reached that end time and there is no more data in the requested window.
  • If you left end open, the token never goes empty, since the stream has no end to reach — it always points at your current position, whether or not new packets are waiting there.
• Retry-After: the recommended number of seconds to wait before your next poll request (max value is 300 seconds). This is the signal to watch on an open stream: its presence means you are caught up to the live edge, so treat it as your polling backoff rather than looking for an empty Continuation-Token.

Query Parameters (Initial Request)

When starting a new stream (no Continuation-Token exists) or to query for data from a period of time, use these parameters to begin polling:

Time Period (UTC, in seconds)

• start time defaults to 7 days ago when not specified.
• Omit end time to leave the stream open and poll for new packets indefinitely.
• Supply an end time if your consumer needs a terminating, empty-token stop condition.

:::tip Granular packet data is available up to 30 days in the past. :::

Device Filtering

• When device_id is provided, only packets from that device will be returned.
• Note: you cannot page indefinitely for single-device queries. The stream closes when it reaches current time.

:::warning Device filtering is provided for troubleshooting. It should not be used for high-volume data retrieval. :::

---

Packet Data Definitions (Response)

Location Object

For TERRESTRIAL packets, all location fields represent the scanning gateway's most recent GPS lock:

• location.timestamp is the timestamp of the location lock.
• location.latitude and location.longitude are the location coordinates.
• location.horizontal_accuracy and location.vertical_accuracy represent accuracy variance in meters.

For SATELLITE packets, location.timestamp and device.timestamp are identical: both represent the time the packet was detected by the satellite.

Device Object

For TERRESTRIAL packets,

• device.timestamp is the timestamp when the data packet was detected by the gateway.
• device.rssi is the received signal strength measured by the gateway.

Gateway Object

For self-provided packets (packets your organization contributed and is also reading back, i.e. provider_id == org_id), the response optionally includes a top-level gateway object. These fields describe the scanning gateway that received the BLE advertisement.

• gateway.gateway_id is the stable gateway UUID issued by Hubble when you register using the Gateway API.
• gateway.service_id is the normalized 16-bit service UUID from the scanned BLE advertisement (e.g. fca6).

:::note The gateway block is omitted entirely for packets sourced from a different organization (e.g. third-party crowdsourced traffic), and is also omitted on self-provided packets when no gateway context was attached at ingest. :::

{
  "packets": [
    {
      "device": {
        "tags": {
          "_env": "production"
        }
      },
      "gateway": {
        "service_id": "fca6"
      }
    }
  ]
}