Storage

List, extract and delete the stored capture files

Captured traffic is written to capture files on the device, one file per capture port and time slice. The API lists the files, deletes them and extracts the packets of a time range, optionally narrowed by a flow filter, as a single pcapng download. The split of the disk between capture files and metadata is configured on the Disk Share page.

API

• Data (CAPTURE_FILE object):

  {
      "path": "/data_raid/profisight/captures/4/capture_20260909130813.cap",
      "interface": "4",
      "key": "/data_raid/profisight/captures/4/capture_20260909130813.cap",
      "creation_ts": 1788952118,
      "start_ts": 1788952092549066055,
      "end_ts": 1788952109711352947,
      "analysis_status": null,
      "custom_session_key": "default",
      "random_session_key": "20260909130701736279076",
      "file_size": 2352947200,
      "pending_deletion": false
  }

  • path - path of the file on the device; used to address the file in other requests
  • interface - capture port the file was recorded on
  • key - identifier of the file, equal to path
  • creation_ts - creation time of the file, epoch seconds
  • start_ts, end_ts - timestamps of the first and last packet, epoch nanoseconds, null for a file without packets
  • analysis_status - always null
  • custom_session_key - name of the capture session the file belongs to
  • random_session_key - identifier of the capture run that produced the file
  • file_size - size in bytes
  • pending_deletion - true while the file waits for asynchronous deletion

• Data (PAGE object):

  {
      "page": 1,
      "page_count": 36,
      "total_count": 72,
      "data": [
          {
              "path": "/data_raid/profisight/captures/4/capture_20260909130813.cap",
              "interface": "4",
              "key": "/data_raid/profisight/captures/4/capture_20260909130813.cap",
              "creation_ts": 1788952118,
              "start_ts": 1788952092549066055,
              "end_ts": 1788952109711352947,
              "analysis_status": null,
              "custom_session_key": "default",
              "random_session_key": "20260909130701736279076",
              "file_size": 2352947200,
              "pending_deletion": false
          },
          {
              "path": "/data_raid/profisight/captures/2/capture_20260909130814.cap",
              "interface": "2",
              "key": "/data_raid/profisight/captures/2/capture_20260909130814.cap",
              "creation_ts": 1788952119,
              "start_ts": 1788952088572661265,
              "end_ts": 1788952109441426260,
              "analysis_status": null,
              "custom_session_key": "default",
              "random_session_key": "20260909130701736279076",
              "file_size": 3940016128,
              "pending_deletion": false
          }
      ]
  }

  • page - the returned page, starting at 1
  • page_count - number of pages for the current results_per_page
  • total_count - number of matching files
  • data - array of CAPTURE_FILE objects; the example is a page of two files out of 72 (results_per_page=2)

• Data (FILTER object), used by the extraction endpoints:

  {
      "from_ts_ns": 1788952092549066055,
      "to_ts_ns": 1788952092569066055,
      "filter_clause": "application = 'HTTP' AND port_server = 80"
  }

  • from_ts_ns, to_ts_ns - optional time range, epoch nanoseconds, each at least 1; a missing bound is replaced by the first or last packet in the storage
  • filter_clause - optional flow filter in the syntax of the Clickhouse Facade table queries; only packets of the matching flows are extracted

• List capture files

  • Path: /api/storage/data/captures
  • Method: GET
  • Minimum user role: viewer
  • URL parameters:
    • page - page to return, default 1
    • results_per_page - files per page, default 5000
    • order - asc (default) or desc
    • start_ts, end_ts - optional, epoch nanoseconds; both must be given, start_ts less than end_ts; selects the files whose first packet lies in the range
  • Request header paths - optional JSON array of file paths to return instead of a time range, for example paths: ["/data_raid/profisight/captures/4/capture_20260909130813.cap"]; cannot be combined with start_ts/end_ts
  • Response on success (200 OK): PAGE object in data; without filters the files are ordered by creation time, with a time range by first packet
  • Response on failure:
    • 400 Bad Request, for example If start_ts or end_ts is present, both start_ts and end_ts must be present., Either nothing, start_ts and end_ts is specified, or paths., If the order argument is present, it must be either asc or desc
    • 404 Not Found, Could not find entry for path: <path> when a path of the paths header does not exist

• Delete capture files

  • Path: /api/storage/data/captures
  • Method: DELETE
  • Minimum user role: operator
  • Request header paths - optional JSON array of file paths to delete
  • URL parameters:
    • start_ts, end_ts - optional, epoch nanoseconds; a missing bound means the beginning or the end of the storage
    • list - true to return the deleted files
  • Selection: the files of the paths header if present, otherwise the files in the time range, otherwise all files
  • Response on success (200 OK): message Successfully started deleting captures. or No captures were found.; with list=true the array of deleted CAPTURE_FILE objects in data
  • Notes: deletion runs asynchronously; until it completes the files are still listed with pending_deletion set to true.

• Check whether packets are available

  • Path: /api/storage/captures/availability
  • Method: POST
  • Minimum user role: viewer
  • Request body: FILTER object, {} for the whole storage
  • Response on success (200 OK): {"message": "Success", "data": {"is_any_packets_written": true}}; false when the storage is empty or the range lies outside the stored packets
  • Response on failure (500 Internal Server Error): the flow filter could not be evaluated

• Request a download token

  • Path: /api/storage/captures/download
  • Method: POST
  • Minimum user role: operator
  • Request body: FILTER object, {} for the whole storage
  • Response on success (200 OK): {"message": "Success", "data": {"token": "6972a45b45579eb8f99bba683bc824b8"}}
  • Response on failure:
    • 204 No Content when the storage is empty or the range lies outside the stored packets
    • 500 Internal Server Error, The user limit:3 of concurrent download sessions is reached or The total limit:5 of concurrent download sessions is reached while that many extractions are running
  • Notes: the token is bound to the session that requested it. The device keeps the 100 most recent tokens; older ones stop working.

• Download the extracted packets

  • Path: /api/storage/captures/download

  • Method: GET

  • Minimum user role: none (no authorization header); the download token in the URL is checked instead

  • URL parameters:

    • token - a token from the POST request above (mandatory)

  • Response on success (200 OK): a pcapng stream, Content-Type: application/x-pcapng, with the header Content-Disposition: attachment; filename="capture_<from>-<to>.pcapng" where the timestamps are UTC, format YYYYMMDDhhmmss. The file is produced while it is sent, so its length is not known in advance.

  • Response on failure (400 Bad Request): Invalid download session token.

  • Example:

    TOKEN_DL=$(curl -sk -X POST -H "authorization: <token>" -H "Content-Type: application/json" \
      -d '{"from_ts_ns": 1788952092549066055, "to_ts_ns": 1788952092569066055}' \
      https://<ip-address>/api/storage/captures/download | python3 -c 'import json,sys; print(json.load(sys.stdin)["data"]["token"])')
    curl -sk -o capture.pcapng "https://<ip-address>/api/storage/captures/download?token=$TOKEN_DL"

Back to Index