Deep Search

The Deep Search API lets you run a tshark display-filter search across a pool of captures and retrieve the IDs of captures that contain matching packets.

Authentication

All endpoints require an API token with the Deep Search permission enabled. Pass the token in the Authorization header:

Authorization: <token>

Endpoints

Create a job

POST /api/v2/deep_search/
Content-Type: application/json

Starts a new deep search job and returns immediately. Poll the status endpoint to check for completion.

Request body fields:

Response: 201 Created

{
  "id": "019ce892-1105-7472-9cff-79bf6a45f9cd",
  "created_at": "2026-03-13T19:00:12.677Z",
  "pool_size": 4,
  "pool_size_bytes": 9549016
}

Get job status

GET /api/v2/deep_search/:id

Returns the current status of a job. Only accessible to the token that created it.

Response: 200 OK

{
  "id": "019ce892-1105-7472-9cff-79bf6a45f9cd",
  "hit_count": 2,
  "searched_count": 4,
  "finished?": true,
  "progress_percent": 100
}

Poll this endpoint until finished? is true before fetching results.

Get results

GET /api/v2/deep_search/:id/results

Returns the capture IDs that matched the display filter. Only accessible to the token that created the job.

Response: 200 OK

["1b475084c04b", "9d0984e899a4"]

Pool resolution

The set of captures to search (the “pool”) is determined in this order:

1. capture_ids provided — creates a pool containing only these captures, filtered to captures readable by the token’s user.
2. criteria.deep_search set — the pool is taken from a prior job’s hit list (chained search). The prior job must be owned by the same token.
3. criteria provided — a pool containing all capture files matching the provided criteria from the token user’s readable captures.
4. Nothing provided — all captures that are readable by the token’s user.

Criteria fields

The criteria object accepts the same fields as the capture search API. For numeric fields, include a matchers key to control the comparison operator.

Matchers

For numeric fields, add a matchers object alongside the field value:

{
  "criteria": {
    "num_packets": "1000",
    "matchers": { "num_packets": ".gt" }
  }
}

Supported matcher values:

Filename

Partial name match across the capture repository.

{ "criteria": { "filename": "sipcall" } }

User

Array of usernames. Returns captures owned by any of the listed users.

{ "criteria": { "user": ["admin", "alice"] } }

Group

Array of group names. Returns captures belonging to any of the listed groups.

{ "criteria": { "group": ["Admin", "NOC"] } }

Tags

Array of tags. By default returns captures that have all specified tags. Use matchers.tags to switch to "or" (any tag).

{
  "criteria": {
    "tags": ["voip", "boston"],
    "matchers": { "tags": "or" }
  }
}

File and data size

Search by file size (size) or PCAP-reported data size (data_size), in bytes. Requires a matcher.

{
  "criteria": {
    "size": "10485760",
    "matchers": { "size": ".gt" }
  }
}

Number of packets

{
  "criteria": {
    "num_packets": "1000",
    "matchers": { "num_packets": ".gt" }
  }
}

Duration

Length of the capture in seconds. Requires a matcher.

{
  "criteria": {
    "duration": "300",
    "matchers": { "duration": ".lt" }
  }
}

Packet, byte, and bit rates

Parameters: avg_packet_rate, data_byte_rate, data_bit_rate, avg_packet_size. All require a matcher.

{
  "criteria": {
    "data_bit_rate": "1000000",
    "matchers": { "data_bit_rate": ".gt" }
  }
}

Upload date and capture date

date (upload date) and cap_date (capture date). Format: mm/dd/yyyy for a single day, mm/dd/yyyy-mm/dd/yyyy for a range.

{ "criteria": { "date": "03/01/2026-03/13/2026" } }

Upload time and capture time

up_time_start + up_time_end and cap_time_start + cap_time_end. Both start and end must be provided. Format: h:mm AM/PM.

{
  "criteria": {
    "cap_time_start": "5:30 AM",
    "cap_time_end": "6:30 AM"
  }
}

Encapsulation

Array of encapsulation types.

{ "criteria": { "encapsulation": ["Ethernet"] } }

File type

Array of file types. Values must match exactly.

{ "criteria": { "file_type": ["Wireshark - pcapng"] } }

Comments, annotations, public, group-writable

{
  "criteria": {
    "hascomments": "true",
    "annotations": "true",
    "ispublic": "true",
    "groupwrite": "true"
  }
}

To search comment text:

{ "criteria": { "comments": "bug 129" } }

Examples

Search an explicit list of captures

curl -X POST https://cloudshark.example.com/api/v2/deep_search/ \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "display_filter": "http",
    "capture_ids": ["1b475084c04b", "5c6f830331cf", "9d0984e899a4"]
  }'

Search all captures with more than 1000 packets

curl -X POST https://cloudshark.example.com/api/v2/deep_search/ \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "display_filter": "http",
    "criteria": {
      "num_packets": "1000",
      "matchers": { "num_packets": ".gt" }
    }
  }'

Search all captures (no filter)

Omit both capture_ids and criteria to search everything the token’s user can read.

curl -X POST https://cloudshark.example.com/api/v2/deep_search/ \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{ "display_filter": "dns" }'

Poll for completion

curl https://cloudshark.example.com/api/v2/deep_search/<id> \
  -H "Authorization: <token>"

Fetch results

curl https://cloudshark.example.com/api/v2/deep_search/<id>/results \
  -H "Authorization: <token>"

Chained search

Refine a prior job’s results with a new display filter. The prior job must belong to the same token.

curl -X POST https://cloudshark.example.com/api/v2/deep_search/ \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "display_filter": "dns",
    "criteria": {
      "deep_search": "019ce892-1105-7472-9cff-79bf6a45f9cd"
    }
  }'

Ownership

Jobs created via the API are owned by the token, not the user account. A token can only read status, fetch results, or chain off jobs it created — not jobs started through the UI or by other tokens, even if they share the same user account.