Skip to main content
For the complete documentation index, see llms.txt.

Hubble Network developer documentation: integrate Bluetooth devices with terrestrial and satellite connectivity.

Retrieve Packets

GET 
/v1/org/:org_id/packets

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.

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.

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).

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.

Request​

Responses​

A page of packets. When the stream has caught up to the present and there is nothing new to return, this still responds 200 with an empty packets array and a Retry-After header — poll again after that many seconds rather than immediately retrying, since immediate retries in this state stay empty.

Response Headers
    Continuation-Token

    A token to indicate how to continue paging

    Retry-After

    The number of seconds to wait before polling again. Only meaningful when the response is an empty page (the stream has no new packets yet): the most recent data has already been retrieved, so this is a suggestion to pause longer between queries rather than poll continuously. Omitted when the page contains packets.