/connections API

POST/GET - /api/connections

Builds an Elasticsearch connections query. Gets a list of nodes and links and returns them to the client.

Parameters:

Param Type Default Description
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
srcField string "ip.src" The source database field name
dstField string "ip.dst:port" The destination database field name
baselineDate number 0 The baseline date range to compare connections against. Default is 0, disabled. Options include: 1x - 1 times query range. 2x - 2 times query range. 4x - 4 times query range. 6x - 6 times query range. 8x - 8 times query range. 10x - 10 times query range. 1 - 1 hour. 6 - 6 hours. 24 - 1 day. 48 - 2 days. 72 - 3 days. 168 - 1 week. 336 - 2 weeks. 720 - 1 month. 1440 - 2 months. 4380 - 6 months. 8760 - 1 year.
baselineVis string "all" Which connections to display when a baseline date range is applied. Default is all. Options include: ‘all’ - All Nodes: all nodes are visible. ‘actual’ - Actual Nodes: nodes present in the “current” timeframe query results are visible. ‘actualold’ - Baseline Nodes: nodes present in the “baseline” timeframe query results are visible. ‘new’ - New Nodes Only: nodes present in the “current” but NOT the “baseline” timeframe are visible. ‘old’ - Baseline Nodes Only: nodes present in the “baseline” but NOT the “current” timeframe are visible.

Returns:

Name Type Description
links array The list of links
nodes array The list of nodes

/connections/csv API

POST/GET - /api/connections/csv OR /api/connections.csv

Builds an Elasticsearch connections query. Gets a list of nodes and links in csv format and returns them to the client.

Parameters:

Param Type Default Description
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
srcField string "ip.src" The source database field name
dstField string "ip.dst:port" The destination database field name

Returns:

Name Type Description
csv csv The csv with the connections requested

/crons API

GET - /api/crons

Retrieves periodic queries a user can view.

Returns:

Name Type Description
queries Array.<ArkimeQuery> A list of query objects.

/cron API

POST - /api/cron

Create a new periodic query.

Returns:

Name Type Description
success boolean Whether the create operation was successful.
text string The success/error message to (optionally) display to the user.
query ArkimeQuery The new query

/cron/:key API

POST - /api/cron/:key

Update a periodic query.

Returns:

Name Type Description
success boolean Whether the update operation was successful.
text string The success/error message to (optionally) display to the user.
query ArkimeQuery The updated query object

/cron/:key API

DELETE - /api/cron/:key

Delete a periodic query.

Returns:

Name Type Description
success boolean Whether the delete operation was successful.
text string The success/error message to (optionally) display to the user.

/featherprint/ip/:ip API

GET - /api/featherprint/ip/:ip

Fetch the persisted featherprint device record for a single IP.

Parameters:

Param Type Description
:ip string The IPv4 / IPv6 address whose device record to fetch.

Returns:

Name Type Description
success boolean True on hit, false on miss.
device object The persisted device record (mac, names, services, classification, …).

/featherprint/search API

GET - /api/featherprint/search

Search persisted featherprint device records by IP / MAC / name. All filters are optional and combine as AND. MAC and name are substring matches; ip must be an exact IP or CIDR (ES ip fields don’t support wildcards).

Parameters:

Param Type Default Description
ip string   Exact IP or CIDR.
mac string   Substring of a MAC address (case insensitive).
name string   Substring of a discovered name (DNS/NBNS/DHCP/SSDP).
limit number 200 Max records to return.

Returns:

Name Type Description
success boolean Whether the search succeeded.
devices array Matching device records, sorted by lastSeen desc.
total number How many records match, which is more than devices holds when limit cut it short.

/featherprint/history/:ip API

GET - /api/featherprint/history/:ip

Return the recent change history for one IP (newIp, newMac, changeMac, changeIp, newName, newService, …). Sorted by ts desc.

Parameters:

Param Type Default Description
:ip string   The IP whose history to fetch.
limit number 50 Max history entries to return.

Returns:

Name Type Description
success boolean Whether the lookup succeeded.
history array Event log entries.

/featherprint/alerts API

GET - /api/featherprint/alerts

Return featherprint alerts (one per event that matched an alertOn* policy flag), sorted by ts desc. Includes both open and acked alerts; callers filter client-side on acked.

Parameters:

Param Type Default Description
limit number 500 Max alerts to return.
acked string   Optional server-side filter: “true” or “false”.

Returns:

Name Type Description
success boolean Whether the lookup succeeded.
alerts array Alert documents, newest first.
total number How many alerts match, which is more than alerts holds when limit cut it short.
openCount number How many alerts are open (not acked), whatever the acked filter and limit.

/featherprint/ack/:id API

POST - /api/featherprint/ack/:id

Acknowledge a single featherprint alert, or un-acknowledge it with acked=false. Ack state is shared by everyone, so this requires one of the featherprintAckRoles (default arkimeAdmin). The alert stays in the index either way; acking just stamps it with the user and timestamp.

Parameters:

Param Type Default Description
:id string   The alert document id to ack.
acked boolean true false to un-acknowledge instead.

Returns:

Name Type Description
success boolean Whether the ack persisted.
acked boolean The ack state now stored on the alert.

/featherprint/ackall API

POST - /api/featherprint/ackall

Acknowledge many featherprint alerts at once, or un-acknowledge them with acked=false. Takes the explicit id list the client is showing rather than acking by query, so what the operator sees on the page is exactly what changes. Requires one of the featherprintAckRoles.

Parameters:

Param Type Default Description
ids array   The alert document ids to ack.
acked boolean true false to un-acknowledge instead.

Returns:

Name Type Description
success boolean Whether the acks persisted.
acked number How many alerts were changed.
failed number How many could not be changed.

/featherprint/lookup API

GET - /api/featherprint/lookup

Transient on-demand fingerprint for an IP. Reads sessions ES directly, never persists, never fires notifiers, and works on any viewer node (no cron-leader requirement). Subnet policy is bypassed – the operator typed the IP explicitly.

Parameters:

Param Type Description
ip string The IP to fingerprint (also accepted as :ip route param).
start number Window start (seconds since epoch). Default: now - 24h.
stop number Window end (seconds since epoch). Default: now.

Returns:

Name Type Description
success boolean Whether the lookup succeeded.
device object The transient device record (or {ip, notFound:true}).

/featherprint/state API

GET - /api/featherprint/state

Return the persisted monitor cursor (lpValue, lastProcessedTs, …) plus the schema-version gate. Used by the UI status row to show how far the monitor has caught up, and to hide the monitor-backed tabs on an old database (lookup still works – it never reads these indices).

Returns:

Name Type Description
success boolean Whether the state lookup succeeded.
state object The persisted monitor state (or null if uninitialized).
dbUpgradeNeeded boolean True if the database predates the featherprint indices.
dbVersion number The current database version (undefined if unknown).
requiredDbVersion number The version that adds the featherprint indices.

/featherprint/config API

GET - /api/featherprint/config

Admin: snapshot of the resolved policy (settings + defaults + per-subnet flag bags). Reflects [featherprint-defaults] and [featherprint-subnet] as parsed at viewer start.

Returns:

Name Type Description
success boolean Always true.
config object {settings, defaults, subnets:[{cidr, flags}]}.

/featherprint/tick API

POST - /api/featherprint/tick

Admin: force an immediate monitor tick. If a tick is already running, the existing run owns the work; the re-entrancy guard in tick() prevents a duplicate scan. Returns status flags so the UI can show why the tick was skipped (notPrimary, alreadyRunning, monitorDisabled).

Returns:

Name Type Description
success boolean Whether the request was processed.
triggered boolean Whether a new tick actually started.
alreadyRunning boolean True if a tick was already in flight.
notPrimary boolean True if this node is not the cron leader.
monitorDisabled boolean True if featherprintMonitorEnabled=false.
dbUpgradeNeeded boolean True if the database predates the featherprint indices.

/histories API

GET - /api/histories

Retrieves a list of histories, or user client requests to the APIs.

Parameters:

Param Type Default Description
date number 1 The number of hours of data to return (-1 means all data). Defaults to 1.
startTime number   If the date parameter is not set, this is the start time of data to return. Format is seconds since Unix EPOCH.
stopTime number   If the date parameter is not set, this is the stop time of data to return. Format is seconds since Unix EPOCH.
searchTerm string   The search text to filter the history list by.
length number 1000 The number of items to return. Defaults to 1,000.
start number 0 The entry to start at. Defaults to 0.
sortField string "timestamp" The field to sort the results by.
desc string true Whether to sort the results descending or ascending. Default is descending.
userId string   The ID of a user to request history results for. Admin can retrieve all users. Normal users can only retrieve their own.

Returns:

Name Type Description
data Array.<History> The list of history results.
recordsTotal number The total number of history results stored.
recordsFiltered number The number of history items matching query.

/history/:id API

DELETE - /api/history/:id

Deletes a history entry (admin only).

Returns:

Name Type Description
success boolean Whether the delete history operation was successful.
text string The success/error message to (optionally) display to the user.

/hunt API

POST - /api/hunt

Creates a new hunt.

Parameters:

Param Type Description
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section
totalSessions number The number of sessions to search.
name string The name of the hunt (not unique).
size number The number of packets to search within each session.
src boolean Whether to search the source packets. Must search src or dst or both.
dst boolean Whether to search the destination packets. Must search src or dst or both.
type string Whether to search raw or reassembled packets.
search string The search text to search for within packets.
searchType string What type of search the text is. Options include: ascii - search for case insensitive ascii text. asciicase - search for case sensitive ascii text. hex - search for hex text. regex - search for text using safe regex. hexregex - search for text using safe hex regex.
notifier Array.<string> An array of notifier IDs to alert when there is an error or when the hunt is complete.
users string The comma separated list of users to be added to the hunt so they can view the results.

Returns:

Name Type Description
success boolean Whether the creation of the hunt was successful.
hunt Hunt The newly created hunt object.
invalidUsers array The list of users that could not be added to the hunt because they were invalid or nonexistent.

/hunts API

GET - /api/hunts

Retrieves a list of hunts.

Parameters:

Param Type Default Description
searchTerm string   The search text to search hunt results for.
length number 10000 The number of items to return. Defaults to 10000.
start number 0 The entry to start at. Defaults to 0
sortField string "created" The field to sort the hunt results by. Defaults to “created”.
desc string false Whether to sort the results in descending order. Default is ascending.
history string false Whether to return only finished hunts. Default is to return queued, paused, and running hunts.

Returns:

Name Type Description
runningJob Hunt If there is a hunt running, returns the currently running hunt object.
data Array.<Hunt> The list of hunts (either finished or queued/paused/running).
recordsTotal number The total number of hunts Arkime has.
recordsFiltered number The number of hunts returned in this result.

/hunt/:id API

DELETE - /api/hunt/:id

Delete a hunt.

Returns:

Name Type Description
success boolean Whether the delete hunt operation was successful.
text string The success/error message to (optionally) display to the user.

/hunt/:id/cancel API

PUT - /api/hunt/:id/cancel

Cancel a hunt. Finishes the hunt and puts it into the hunt history.

Returns:

Name Type Description
success boolean Whether the cancel hunt operation was successful.
text string The success/error message to (optionally) display to the user.

/hunt/:id/pause API

PUT - /api/hunt/:id/pause

Pause a hunt.

Returns:

Name Type Description
success boolean Whether the pause hunt operation was successful.
text string The success/error message to (optionally) display to the user.

/hunt/:id/play API

PUT - /api/hunt/:id/play

Play a hunt.

Returns:

Name Type Description
success boolean Whether the play hunt operation was successful.
text string The success/error message to (optionally) display to the user.

/hunt/:id/removefromsessions API

PUT - /api/hunt/:id/removefromsessions

Remove the hunt ID and name from matched sessions.

Returns:

Name Type Description
success boolean Whether the operation was successful.
text string The success/error message to (optionally) display to the user.

/hunt/:id API

PUT - /api/hunt/:id

Update a hunt - can only update description & roles

Parameters:

Param Type Description
hunt Hunt The new hunt data

Returns:

Name Type Description
success boolean Whether the operation was successful.
text string The success/error message to (optionally) display to the user.

/hunt/:id/users API

POST - /api/hunt/:id/users

Add user(s) to a hunt.

Parameters:

Param Type Description
users string Comma separated list of user ids to add to the hunt.

Returns:

Name Type Description
success boolean Whether the add users operation was successful.
users array The list of users that were added to the hunt.
invalidUsers array The list of users that could not be added to the hunt because they were invalid or nonexistent.

/hunt/:id/user/:user API

DELETE - /api/hunt/:id/user/:user

Remove user(s) from a hunt.

Returns:

Name Type Description
success boolean Whether the remove users operation was successful.
users array The list of users who have access to the hunt.
invalidUsers array The list of users that could not be removed from the hunt because they were invalid or nonexistent.

/fields API

GET - /api/fields

Gets available database field objects pertaining to sessions.

Parameters:

Param Type Default Description
array boolean false Whether to return an array of fields, otherwise returns a map

Returns:

Name Type Description
  array/map The map or list of database fields

/files API

GET - /api/files

Gets a list of PCAP files that Arkime knows about.

Parameters:

Param Type Default Description
length number 10 The number of items to return. Defaults to 10, Max is 10,000
start number 0 The entry to start at. Defaults to 0

Returns:

Name Type Description
data Array The list of files
recordsTotal number The total number of files Arkime knows about
recordsFiltered number The number of files returned in this result

/valueactions API

GET - /api/valueactions

Retrieves the actions that can be performed on meta data values.

Returns:

Name Type Description
  object The list of actions that can be performed on data values.

/fieldactions API

GET - /api/fieldactions

Retrieves the actions that can be performed on fields.

Returns:

Name Type Description
  object The list of actions that can be performed on fields.

/reversedns API

GET - /api/reversedns

Retrieves the domain names associated with an IP address.

Parameters:

Param Type Description
ip string The IP to search domain names for.

Returns:

Name Type Description
domains string A comma separated string list of all the matching domain names.

/upload API

POST - /api/upload

Uploads PCAP files to Arkime. This API is really only useful for demo sites and very special cases. Instead you almost always should just run capture locally, which will be much more efficient and not duplicate the PCAP. See https://arkime.com/faq#how-do-i-import-existing-pcaps

Parameters:

Param Type Description
tags string A comma separated list of tags to add to each session created.

/clusters API

GET - /api/clusters

Retrieves a list of known configured Arkime clusters (if in Multi Viewer mode).

Returns:

Name Type Description
active Array The active Arkime clusters.
inactive Array The inactive Arkime clusters.

/remoteclusters API

GET - /api/remoteclusters

Retrieves a list of known configured remote Arkime clusters.

Returns:

Name Type Description
remoteclusters Object Key/value pairs of remote Arkime clusters, the key being the name of the cluster

/appinfo API

GET - /api/appinfo

Retrieves information that the app uses on every page: eshealth, currentuser, views, remoteclusters, clusters, fields, fieldsmap, fieldhistory

Returns:

Name Type Description
eshealth ESHealth The OpenSearch/Elasticsearch cluster health status and information.
currentuser ArkimeUser The currently logged in user
views Array.<ArkimeView> A list of views accessible to the logged in user
remoteclusters Object A list of known remote Arkime clusters
clusters Array A list of known configured Arkime clusters (if in Multi Viewer mode)
fields Array Available database field objects pertaining to sessions
fieldsmap Array Available database field objects pertaining to sessions
fieldhistory Object The user’s field history for the search expression input

/buildquery API

POST/GET - /api/buildquery

This API allows you to build the query that Arkime viewer would use so you can use yourself against OpenSearch/Elasticsearch.

Parameters:

Param Type Description
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section

Returns:

Name Type Description
query object The elasticsearch query
indices object The elasticsearch indices that contain sessions in this query

Example

Returns the OpenSearch/Elasticsearch query for all the sessions with the source IP of 1.2.3.4
  curl -v 'http://localhost:8005/api/buildquery?date=-1&expression=ip.src%3D%3D1.2.3.4'

/sessions API

POST/GET - /api/sessions OR /sessions.json

Return all the JSON formatted session data based on the query parameters.

Parameters:

Param Type Description
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section

Returns:

Name Type Description
map object The data to populate the sessions map
graph object The data to populate the sessions timeline graph
data array The list of sessions with the requested fields
recordsTotal number The total number of sessions Arkime knows about
recordsFiltered number The number of sessions matching query

Example

Returns all the sessions with the source IP of 1.2.3.4
  curl -v 'http://localhost:8005/api/sessions?date=-1&expression=ip.src%3D%3D1.2.3.4'

/sessions/csv API

POST/GET - /api/sessions/csv OR /sessions.csv

Return all the CSV formatted session data based on the query parameters.

Parameters:

Param Type Description
ids string Comma separated list of sessions to retrieve
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section

Returns:

Name Type Description
csv csv The csv with the sessions requested

Example

Returns all the sessions with the source IP of 1.2.3.4
  curl -v 'http://localhost:8005/api/sessions/csv?date=-1&expression=ip.src%3D%3D1.2.3.4'

/spiview API

POST/GET - /api/spiview

Builds an elasticsearch session query. Gets a list of field values with counts and returns them to the client.

Parameters:

Param Type Description
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section
spi string Comma separated list of db fields to return. Optionally can be followed by :{count} to specify the number of values returned for the field (defaults to 100).

Returns:

Name Type Description
map object The data to populate the sessions map
graph object The data to populate the sessions timeline graph
spi object The list of spi fields with values and counts
protocols object The list of protocols with counts
recordsTotal number The total number of sessions Arkime knows about
recordsFiltered number The number of sessions matching query

Example

Returns first 100 unique values for the destination.ip field for last 10 hours
  curl -v 'http://localhost:8005/api/spiview?spi=destination.ip:200&date=10

/spigraph API

POST/GET - /api/spigraph

Builds an elasticsearch session query. Gets a list of values for a field with counts and graph data and returns them to the client.

Parameters:

Param Type Default Description
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
exp string   The expression field to return data for. Either exp or field is required, field is given priority if both are present.
field string "node" The database field to return data for. Either exp or field is required, field is given priority if both are present.
metric string   Optional numeric (integer) field exp (dashboard widgets). When set, its per-value sum is added as a Histo timeline series and per-item total (drives heatmap intensity / treemap size). 'sessions' and non-numeric fields are ignored (doc_count is used).
metricAgg string   Optional percentile of the metric instead of its sum: ‘p50’ (the median), ‘p90’, ‘p95’ or ‘p99’. The graph and each item then carry a :pHisto series, the percentile of each time bucket, and the item's :pHisto total is the percentile over the whole time range (sort by it to rank the values). Not with interval=hourOfWeek, and refused by a multi viewer.

Returns:

Name Type Description
map object The data to populate the main/aggregate spigraph sessions map
graph object The data to populate the main/aggregate spigraph sessions timeline graph
items array The list of field values with their corresponding timeline graph and map data
recordsTotal number The total number of sessions Arkime knows about
recordsFiltered number The number of sessions matching query

/spigraphhierarchy API

POST/GET - /api/spigraphhierarchy

Builds an elasticsearch session query. Gets a list of values for each field with counts and returns them to the client.

Parameters:

Param Type Default Description
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
exp string   Comma separated list of db fields to populate the graph/table.
size number 20 The number of values to return for each field
sizes string   Comma separated per-field sizes, overriding size for the fields they line up with
other boolean false When set each level gets an “Other” child holding the sessions outside its top values
mode string   ‘unique’ returns each field’s own top values (independent lists, like /unique per field, not combinations like /multiunique) in columns instead of the nested results
strictly boolean false When set the entire session must be inside the date range to be observed, otherwise if it overlaps it is displayed. Overwrites the bounding parameter, sets bounding to ‘both’

Returns:

Name Type Description
hierarchicalResults object The nested data to populate the treemap or pie (an “Other” child carries other: true)
tableResults array The list data to populate the table
columns array With mode=unique only (and instead of the two above): one { exp, values: [{ name, size, srcips, dstips }] } per field, in exp order

/unique API

POST/GET - /api/unique

Builds an elasticsearch session query. Gets a list of unique field values (with or without counts) and sends them to the client.

Parameters:

Param Type Default Description
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
counts number 0 Whether to return counts with the list of unique field values. Defaults to 0. 0 = no counts, 1 - counts.
exp string   The expression field to return unique data for. Either exp or field is required, field is given priority if both are present.
field string   The database field to return unique data for. Either exp or field is required, field is given priority if both are present.

Returns:

Name Type Description
  string The list of unique fields (with counts if requested)

/multiunique API

POST/GET - /api/multiunique

Builds an elasticsearch session query. Gets an intersection of unique field values (with or without counts) and sends them to the client.

Parameters:

Param Type Default Description
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
counts number 0 Whether to return counts with the list of unique field values. Defaults to 0. 0 = no counts, 1 - counts.
exp string   Comma separated list of expression fields to return unique data for.

Returns:

Name Type Description
  string The list of an intersection of unique fields (with counts if requested)

/session/:id API

GET - /api/session/:id

Gets all the fields for a session as JSON.

Parameters:

Param Type Description
id string The ID of the session to retrieve

Returns:

Name Type Description
  object The session fields as a JSON object

/session/:nodeName/:id/detail API

GET - /api/session/:nodeName/:id/detail

Gets SPI data for a session.

Returns:

Name Type Description
{ html, info } object the detail html plus the session
fields the client row may not carry (rootId, communityId, packets, etc.)    

/session/:nodeName/:id/packets API

GET - /api/session/:nodeName/:id/packets

Gets packets for a session.

Returns:

Name Type Description
  html The html to display as session packets

/session/:nodeName/:id/tshark API

GET - /api/session/:nodeName/:id/tshark

Runs tshark against the session’s pcap and streams a converted PDML dissection as NDJSON (one JSON object per packet per line). Always dispatched on the central viewer that received the request; the pcap is fetched from the owning node when needed.

Each emitted line looks like: {“layers”:[ {“name”:”frame”,”label”:”Frame 1: …”,”fields”:[ {“name”:”frame.len”,”label”:”Frame Length: 197”,”show”:”197”,”pos”:0,”size”:0}, …] }, {“name”:”eth”,”label”:”Ethernet II, …”,”fields”:[ {“name”:”eth.dst”,”label”:”Destination: …”,”show”:”…”,”value”:”","pos":0,"size":6, "fields":[...]} ]}, ... ], "bytes":""}

Parameters:

Param Type Default Description
hidden string false “true” to include fields tshark marks hide=”yes”
payload string false “true” to include the raw “data” proto layer for unparsed payload bytes (otherwise passes --disable-protocol data to tshark)
bytes string true “false” to omit the “bytes” hex of each frame (“bytes” carries at most the first 16KB of a frame; frame.cap_len has the real captured length)
length number   number of packets to dissect, capped at the tsharkMaxPackets config value (which is also the default)

Returns:

Name Type Description
One JSON ndjson encoded packet per line

/sessions/addtags API

POST - /api/sessions/addtags

Add tag(s) to individual session(s) by id or by query.

Parameters:

Param Type Default Description
tags string   Comma separated list of tags to add to session(s)
ids string   Comma separated list of sessions to add tag(s) to
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
segments string "no" Whether to add tags to linked session segments. Default is no. Options include: no - Don’t add tags to linked segments all - Add tags to all linked segments time - Add tags to segments occurring in the same time period

Returns:

Name Type Description
success boolean Whether the add tags operation was successful
text string The success/error message to (optionally) display to the user

/sessions/removetags API

POST - /api/sessions/removetags

Removes tag(s) from individual session(s) by id or by query.

Parameters:

Param Type Default Description
tags string   Comma separated list of tags to remove from session(s)
ids string   Comma separated list of sessions to remove tag(s) from
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
segments string "no" Whether to remove tags from linked session segments. Default is no. Options include: no - Don’t remove tags from linked segments all - Remove tags from all linked segments time - Remove tags from segments occurring in the same time period

Returns:

Name Type Description
success boolean Whether the remove tags operation was successful
text string The success/error message to (optionally) display to the user

/sessions/summary API

POST/GET - /api/sessions/summary

Backs the Arkime tab modular dashboard. Streams a JSON array whose first element is the top-level stats/map/graph chunk (omitted when noStats is set), followed by one chunk per requested widget, terminated by an empty object.

Parameters:

Param Type Description  
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section  
widgets Array.<object> Per-widget aggregation specs. Each: { id (stable widget id), field (Arkime field exp; may be omitted with total:true), total (when true, aggregate the metrics over the whole result set instead of per field value — a single data item), length (top/bottom N, clamped 1-1000), order (‘asc’ ‘desc’), orderBy (‘value’ default: the Top/Bottom N by the sort metric or session count; ‘key’: by the field’s own value, so asc is the N smallest values or names), metricType (‘sessions’ or a numeric field exp aggregated per value), metrics (array of field exps, each aggregated per value — the multi-metric table’s columns; falls back to [metricType]), metricAgg (‘sum’ default, ‘avg’, ‘min’, ‘max’, ‘cardinality’, or a percentile ‘p50’ (the median), ‘p90’, ‘p95’ or ‘p99’; cardinality accepts any field, the others numeric fields only; in a multi viewer a cardinality is the largest cluster’s count, a lower bound, and a percentile is refused), sortMetric (which of metrics orders the Top/Bottom N; ‘sessions’ or unset orders by session count), splitField (optional second field exp; each value’s top splitLength sub-values are returned in data[].split for stacked/grouped bars), splitLength (sub-values per value, clamped 1-50, default 5), bucketInterval (numeric fields only: bucket the field’s values into ranges of this width instead of one bucket per value; each data[] item is then a range, item ‘-' with range: [start, end]), other (when true and the metric is the session count or a sum, also return what falls outside the top N), box (when true, also return the spread of the first numeric metric over each value's sessions, for a box plot; refused by a multi viewer), expression (local filter ANDed with the global search) }. An empty array yields a stats-only response. At most 100 widgets.
fields string Legacy alternative to widgets: a comma-separated string of field exps (each becomes a default widget), at most 100. One of widgets or fields is required.  
noStats boolean When true, skip the top-level stats/map/graph chunk (incremental single-widget fetches that don’t change the dashboard totals).  
length number Default top/bottom N for widgets that don’t set their own. Default: 20  
order string Default sort order (‘asc’ ‘desc’) for widgets that don’t set their own. Default: desc

Returns:

Name Type Description
summary array A streamed JSON array: [ {stats/map/graph}, {widget}, …, {} ]. Each widget chunk carries { id, field, viewMode, metricType, metricAgg, length, order, orderBy, expression, data[] } or { id, field, error } on per

/session/:nodeName/:id/body/:bodyType/:bodyNum/:bodyName API

GET - /api/session/:nodeName/:id/body/:bodyType/:bodyNum/:bodyName

Retrieves a file that was transferred in a session.

Returns:

Name Type Description
file file The file in the session

/session/:nodeName/:id/bodypng/:bodyType/:bodyNum/:bodyName API

GET - /api/session/:nodeName/:id/bodypng/:bodyType/:bodyNum/:bodyName

Retrieves a bitmap image representation of the bytes in a file.

Returns:

Name Type Description
image image/png The bitmap image.

/sessions/pcap API

GET - /api/sessions/pcap OR /api/sessions.pcap

Retrieve the raw session data in pcap format.

Parameters:

Param Type Default Description
ids string   The list of ids to return sessions for
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
segments boolean false When set return linked segments
check boolean false When set don’t download anything, instead return JSON describing whether the sessions span more than one link type (needsPcapng) and so can only be downloaded as pcapng

Returns:

Name Type Description
  pcap A PCAP file with the sessions requested. A 400 JSON error with i18n api.sessions.pcapngRequired is returned instead when the sessions span more than one link type.

Example

Returns pcap for sessions with the source IP of 1.2.3.4
  curl -v 'http://localhost:8005/api/sessions/pcap/anyfilename.pcap?date=-1&expression=ip.src%3D%3D1.2.3.4'

/sessions/pcapng API

GET - /api/sessions/pcapng OR /api/sessions.pcapng

Retrieve the raw session data in pcapng format.

Parameters:

Param Type Default Description
ids string   The list of ids to return sessions for
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
segments boolean false When set return linked segments

Returns:

Name Type Description
  pcap A PCAPNG file with the sessions requested

/session/entire/:nodeName/:id/pcap API

GET - /api/session/entire/:nodeName/:id/pcap OR /api/session/entire/:nodeName/:id.pcap

Retrieve the pcap for a session given the session id and node name.

Parameters:

Param Type Default Description
check boolean false When set don’t download anything, instead return JSON describing whether the session spans more than one link type (needsPcapng) and so can only be downloaded as pcapng

Returns:

Name Type Description
  pcap A PCAP file with the session requested. A 400 JSON error with i18n api.sessions.pcapngRequired is returned instead when the session spans more than one link type.

/session/entire/:nodeName/:id/pcapng API

GET - /api/session/entire/:nodeName/:id/pcapng OR /api/session/entire/:nodeName/:id.pcapng

Retrieve the pcapng for a session given the session id and node name.

Returns:

Name Type Description
  pcap A PCAPNG file with the session requested

/session/raw/:nodeName/:id/png API

GET - /api/session/raw/:nodeName/:id/png OR /api/session/raw/:nodeName/:id.png

Retrieve a bitmap image representation of packets in a session given the session id and node name.

Parameters:

Param Type Default Description
type string "src" Whether to retrieve the src (source) or dst (destination) packets bitmap image. Defaults to src.

Returns:

Name Type Description
image image/png The bitmap image.

/session/raw/:nodeName/:id API

GET - /api/session/raw/:nodeName/:id

Retrieve raw packets for a session given the session id and node name.

Parameters:

Param Type Default Description
type string "src" Whether to retrieve the src (source) or dst (destination) raw packets. Defaults to src.

Returns:

Name Type Description
  string The source or destination packet text.

/sessions/bodyhash/:hash API

GET - /api/sessions/bodyhash/:hash

Retrieve a file given a hash of that file.

Parameters:

Param Type Description
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section

Returns:

Name Type Description
file file The file that matches the hash

/session/:nodeName/:id/bodyhash/:hash API

GET - /api/session/:nodeName/:id/bodyhash/:hash

Retrieve a file from a specific node given a hash of that file.

Parameters:

Param Type Description
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section

Returns:

Name Type Description
file file The file that matches the hash

/delete API

GET - /api/delete

Delete SPI and/or scrub PCAP data (remove permission required).

Parameters:

Param Type Default Description
ids string   Comma separated list of sessions to delete
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
removeSpi string false Whether to remove the SPI data.
removePcap string true Whether to remove the PCAP data.

Returns:

Name Type Description
success boolean Whether the operation was successful
text string The success/error message to (optionally) display to the user

/shareable API

POST - /api/shareable

Creates a shareable item.

Returns:

Name Type Description
success boolean Whether the create operation was successful.
text string The success/error message.
id string The ID of the new shareable item.
shareable object The new shareable item.

/shareable/:id API

GET - /api/shareable/:id

Gets a shareable item by ID. User must have view permission.

Returns:

Name Type Description
success boolean Whether the get operation was successful.
shareable object The shareable item.

/shareable/:id API

PUT - /api/shareable/:id

Updates a shareable item. Only creator or editUsers/editRoles can update. Creator and created date are not changed. Updated date is set to now.

Returns:

Name Type Description
success boolean Whether the update operation was successful.
text string The success/error message.
shareable object The updated shareable item.

/shareable/:id API

DELETE - /api/shareable/:id

Deletes a shareable item. Only creator or arkimeAdmin can delete.

Returns:

Name Type Description
success boolean Whether the delete operation was successful.
text string The success/error message.

/shareables API

GET - /api/shareables

Lists shareable items. Returns items user has permission to view/edit.

Parameters:

Param Type Default Description
type string   Only list this type, omit to list every type
searchTerm string   Substring match against name, description, type and creator
sort string "name" Field to sort by: name, type, description, creator, created or updated
desc string false “true” to sort descending

Returns:

Name Type Description
data array Array of shareable items with { id, type, name, description,
data, creator, shared, viewUsers, viewRoles, editUsers, editRoles, canEdit, canDelete }    
recordsTotal number Total records matching query
recordsFiltered number Total records after filtering

/shortcuts API

GET - /api/shortcuts

Retrieves a list of shortcuts.

Parameters:

Param Type Default Description
map string false Whether to return a list or a map. Default is list.
sort string "name" The field to sort the results by.
desc string true Whether to sort the results descending or ascending. Default is descending.
searchTerm string   The search text to filter the shortcut list by.
length number 50 The number of items to return. Defaults to 50.
start number 0 The entry to start at. Defaults to 0.
fieldType string   Filter the results by type (number, ip, or string).
fieldFormat string false Sends a help field with the shortcut with the description + the values of the shortcut.

Returns:

Name Type Description
data Array.<Shortcut> The list of shortcut results.
recordsTotal number The total number of shortcut results stored.
recordsFiltered number The number of shortcut items returned in this result.

/shortcut API

POST - /api/shortcut

Creates a new shortcut.

Parameters:

Param Type Description
name string The name of the new shortcut.
type string The type of the shortcut (number, ip, or string).
value string The shortcut value.
description string The optional description of this shortcut.
users string A comma separated list of users that can view this shortcut.
roles Array The roles that can view this shortcut.

Returns:

Name Type Description
shortcut Shortcut The new shortcut object.
success boolean Whether the create shortcut operation was successful.

/shortcut/:id API

PUT - /api/shortcut/:id

Updates a shortcut.

Parameters:

Param Type Description
name string The name of the shortcut.
type string The type of the shortcut (number, ip, or string).
value string The shortcut value.
description string The optional description of this shortcut.
users string A comma separated list of users that can view this shortcut.
roles Array The roles that can view this shortcut.
editRoles Array The roles that can edit this shortcut.

Returns:

Name Type Description
shortcut Shortcut The updated shortcut object.
success boolean Whether the update operation was successful.
text string The success/error message to (optionally) display to the user.

/shortcut/:id API

DELETE - /api/shortcut/:id

Deletes a shortcut.

Returns:

Name Type Description
success boolean Whether the delete shortcut operation was successful.
text string The success/error message to (optionally) display to the user.

/eshealth API

GET - /api/eshealth

Retrieve OpenSearch/Elasticsearch health and stats There is no auth necessary to retrieve eshealth

Returns:

Name Type Description
health ESHealth The elasticsearch cluster health status and info

/stats API

GET - /api/stats

Fetches a list of stats for each node in the cluster.

Parameters:

Param Type Default Description
filter string   Search text to filter the list of nodes by.
length number 500 The number of nodes to return. Defaults to 500.
start number 0 The entry to start at. Defaults to 0.
sortField string "nodeName" The field to sort the node list by.
desc string false Whether to return the results in descending order. Defaults to “false”.
hide string   Which nodes to exclude from the results. Options include: none - show all nodes. old - hide out of date nodes (nodes whose current time is behind by at least 5 minutes). nosession - hide nodes without sessions. both - hide out of date nodes and nodes without sessions.

Returns:

Name Type Description
data array List of nodes with their corresponding stats.
recordsTotal number The total number of nodes.
recordsFiltered number The number of nodes returned in this result.

/dstats API

GET - /api/dstats

Fetches a list of detailed stats for different fields pertaining to a node to populate a cubism graph. Cubism GitHub

Parameters:

Param Type Default Description
nodeName string   The name of the node to get the detailed stats for.
name string   The name of the field to get the detailed stats for.
start number   The start time of data to return. Format is seconds since Unix EPOCH.
stop number   The stop time of data to return. Format is seconds since Unix EPOCH.
step number   The context step of the cubism graph in seconds.
interval number 60 The time interval to search for.
size number 1440 The size of the cubism graph. Defaults to 1440.

Returns:

Name Type Description
  array List of values to populate the cubism graph.

/esstats API

GET - /api/esstats

Fetches a list of stats for each OpenSearch/Elasticsearch cluster.

Parameters:

Param Type Default Description
filter string   Search text to filter the list of OpenSearch/Elasticsearch clusters by.
sortField string "nodeName" The field to sort the OpenSearch/Elasticsearch clusters list by.
desc string false Whether to return the results in descending order. Defaults to “false”.

Returns:

Name Type Description
data array List of ES clusters with their corresponding stats.
recordsTotal number The total number of ES clusters.
recordsFiltered number The number of ES clusters returned in this result.

/esindices API

GET - /api/esindices

Fetches a list of OpenSearch/Elasticsearch indices.

Parameters:

Param Type Default Description
filter string   Search text to filter the list of OpenSearch/Elasticsearch indices by.
sortField string "index" The field to sort the OpenSearch/Elasticsearch indices list by.
desc string false Whether to return the results in descending order. Defaults to “false”.

Returns:

Name Type Description
data array List of ES indices with their corresponding stats.
recordsTotal number The total number of ES indices.
recordsFiltered number The number of ES indices returned in this result.

/esindices/:index API

DELETE - /api/esindices/:index

Deletes an OpenSearch/Elasticsearch index (admin and remove access only).

Returns:

Name Type Description
success boolean Whether the delete index operation was successful.
text string The success/error message to (optionally) display to the user.

/esindices/:index/optimize API

POST - /api/esindices/:index/optimize

Optimizes an OpenSearch/Elasticsearch index (admin only).

Returns:

Name Type Description
success boolean Always true, the optimizeIndex function might block. Check the logs for errors.

/esindices/:index/close API

POST - /api/esindices/:index/close

Closes an OpenSearch/Elasticsearch index (admin only).

Returns:

Name Type Description
success boolean Whether the close index operation was successful.
text string The success/error message to (optionally) display to the user.

/esindices/:index/open API

POST - /api/esindices/:index/open

Opens an OpenSearch/Elasticsearch index (admin only).

Returns:

Name Type Description
success boolean Always true, the openIndex function might block. Check the logs for errors.

/esindices/:index/shrink API

POST - /api/esindices/:index/shrink

Shrinks an OpenSearch/Elasticsearch index (admin only).

Parameters:

Param Type Description
target string The index name to shrink the index to.
numShards number The number of shards to shrink the index to.

Returns:

Name Type Description
success boolean Whether the shrink operation was successful.
text string The success/error message to (optionally) display to the user.

/estasks API

GET - /api/estasks

Fetches OpenSearch/Elasticsearch tasks.

Parameters:

Param Type Default Description
filter string   Search text to filter the list of ES tasks by.
cancellable string false Whether to return only cancellable tasks. Default is “false”.
sortField string "action" The field to sort the ES task list by.
desc string false Whether to return the results in descending order. Defaults to “false”.
size number 1000 The number of ES tasks to return. Defaults to 1000.

Returns:

Name Type Description
data array List of ES tasks with their corresponding stats.
recordsTotal number The total number of ES tasks.
recordsFiltered number The number of ES tasks returned in this result.

/estasks/:id/cancel API

POST - /api/estasks/:id/cancel

Cancels an OpenSearch/Elasticsearch task (admin only).

Returns:

Name Type Description
success boolean Whether the cancel task operation was successful.
text string The success/error message to (optionally) display to the user.

/estasks/:id/cancelwith API

POST - /api/estasks/:id/cancelwith

Cancels an OpenSearch/Elasticsearch task by opaque id. Used to cancel running tasks that a user has created allowing a user to cancel their own tasks.

Returns:

Name Type Description
success boolean Whether the cancel task operation was successful.
text string The success/error message to (optionally) display to the user.

/db/:db/queries API

GET - /api/db/:db/queries

Lists the queries running on a non OpenSearch/Elasticsearch db, like ClickHouse for the sessions. The query text is only returned to dbAdmin users.

Parameters:

Param Type Default Description
db string   The db, sessions, cluster or users.
filter string   A regex to filter the user, db user or query by.
sortField string "elapsed" The field to sort by.
desc boolean true Sort descending.

Returns:

Name Type Description
data Array The queries: id, user, dbUser, app, state, elapsed, rowsRead, bytesRead, memory, cancelled, query, each backend fills what it can.
recordsTotal number The number of running queries.
recordsFiltered number The number of queries returned.

/db/:db/queries/:id/kill API

POST - /api/db/:db/queries/:id/kill

Kills a query running on a non OpenSearch/Elasticsearch db (dbAdmin only).

Parameters:

Param Type Description
db string The db, sessions, cluster or users.
id string The query id from /api/db/:db/queries.

Returns:

Name Type Description
success boolean Whether the query was found and killed.
text string The success/error message to (optionally) display to the user.

/db/:db/tables API

GET - /api/db/:db/tables

Lists the tables, or for ClickHouse the table partitions, of a non OpenSearch/Elasticsearch db.

Parameters:

Param Type Default Description
db string   The db, sessions, cluster or users.
filter string   A regex to filter the table or partition by.
sortField string "table" The field to sort by.
desc boolean false Sort descending.

Returns:

| Name | Type | Description | | — | — | — | | data | Array| The tables, each backend fills the fields it has: id, table, partition, rows, parts, patchParts, dead, bytes, compressed, uncompressed, tableBytes, indexBytes, memory, cached, first, last, modified, lastVacuum, lastAnalyze. | | recordsTotal | number| The number of tables. | | recordsFiltered | number| The number of tables returned. |

/db/:db/tables/:id/:action API

POST - /api/db/:db/tables/:id/:action DELETE - /api/db/:db/tables/:id

Runs an action on a table or partition of a non OpenSearch/Elasticsearch db (dbAdmin only), the DELETE drops it and also needs removeEnabled. ClickHouse can optimize and drop partitions, Postgres can vacuum tables.

Parameters:

Param Type Description
db string The db, sessions, cluster or users.
id string The table id from /api/db/:db/tables.
action string optimize or vacuum, the ones the db supports.

Returns:

Name Type Description
success boolean Whether the action ran (an optimize or vacuum is only started).
text string The success/error message to (optionally) display to the user.

/estasks/cancelall API

POST - /api/estasks/cancelall

Cancels all running OpenSearch/Elasticsearch tasks (admin only).

Returns:

Name Type Description
success boolean Whether the cancel all tasks operation was successful.
text string The success/error message to (optionally) display to the user.

/esadmin API

GET - /api/esadmin

Fetches all OpenSearch/Elasticsearch settings that a user can change (requires the dbAdmin role).

Returns:

Name Type Description
settings array List of ES settings that a user can change

/esadmin/set API

POST - /api/esadmin/set

Sets OpenSearch/Elasticsearch settings (requires the dbAdmin role).

Returns:

Name Type Description
success boolean Whether saving the settings was successful.
text string The success/error message to (optionally) display to the user.

/esadmin/reroute API

POST - /api/esadmin/reroute

Try to restart any shard migrations that have failed or paused (requires the dbAdmin role).

Returns:

Name Type Description
success boolean Whether the reroute was successful.
text string The success/error message to (optionally) display to the user.

/esadmin/flush API

POST - /api/esadmin/flush

Flush and refresh any data waiting in OpenSearch/Elasticsearch to disk (requires the dbAdmin role).

Returns:

Name Type Description
success boolean Always true
text string The success message to (optionally) display to the user.

/esadmin/unflood API

POST - /api/esadmin/unflood

Try and clear any indices marked as flooded (requires the dbAdmin role).

Returns:

Name Type Description
success boolean Always true
text string The success message to (optionally) display to the user.

/esadmin/clearcache API

POST - /api/esadmin/clearcache

Try and clear the cache for all indices (requires the dbAdmin role).

Returns:

Name Type Description
success boolean Whether clearing the cache was successful.
text string The success/error message to (optionally) display to the user.

/esadmin/allocation API

GET - /api/esadmin/allocation

Provides an explanation for shard allocation in the cluster (requires the dbAdmin role). Returns details about why shards are assigned or unassigned.

Parameters:

Param Type Description
index string Optional specific index name to explain
shard number Optional specific shard number to explain
primary boolean Optional whether the shard is primary (true) or replica (false)

Returns:

Name Type Description
allocation object The cluster allocation explanation including node decisions and shard state

/esshards API

GET - /api/esshards

Fetches all OpenSearch/Elasticsearch shards

Parameters:

Param Type Default Description
filter string   Search text to filter the list of OpenSearch/Elasticsearch shards by.
show string "all" Which types of shard to show. Options include: all - show all shards. notstarted - show unstarted shards. INITIALIZING - show initializing shards. RELOCATING - show relocating shards. UNASSIGNED - show unassigned shards.
desc string false Whether to return the results in descending order. Defaults to “false”.

Returns:

Name Type Description
nodes array List of ES data nodes.
indices array List of ES indices.
nodeExcludes array List of node names that disallow the allocation of shards.
ipExcludes array List of node ips that disallow the allocation of shards.

/esshards/:type/:value/exclude API

POST - /api/esshards/:type/:value/exclude

Exclude OpenSearch/Elasticsearch node by ip or name (admin only).

Returns:

Name Type Description
success boolean Whether exclude node operation was successful.
text string The success/error message to (optionally) display to the user.

/esshards/:type/:value/include API

POST - /api/esshards/:type/:value/include

Include OpenSearch/Elasticsearch node by ip or name (admin only).

Returns:

Name Type Description
success boolean Whether include node operation was successful.
text string The success/error message to (optionally) display to the user.

/esshards/:index/:shard/delete API

POST - /api/esshards/:index/:shard/delete

Deletes an OpenSearch/Elasticsearch shard (admin only).

Returns:

Name Type Description
success boolean Whether the delete shard operation was successful.
text string The success/error message to (optionally) display to the user.

/esrecovery API

GET - /api/esrecovery

Returns information about ongoing and completed shard recoveries for indices.

Parameters:

Param Type Default Description
filter string   Search text to filter the list of indices by.
sortField string "index" The field to sort the indices by.
desc string false Whether to return the results in descending order. Defaults to “false”.
show string "active" Whether to show “all” or “active” recovering indices.

Returns:

Name Type Description
data array List of indices with their corresponding stats.
recordsTotal number The total number of indices.
recordsFiltered number The number of indices returned in this result.

/parliament API

GET - /api/parliament

Returns information all the Arkime clusters configured in your Parliament. See the parliament definition here (subject to change).

Returns:

Name Type Description
data array List of fields that describe the cluster stats.
recordsTotal number The total number of stats.
recordsFiltered number The number of stats returned in this result.

/user/settings API

GET - /api/user/settings

Retrieves an Arkime user’s settings.

Returns:

Name Type Description
settings ArkimeSettings The user’s configured settings

/user/settings API

POST - /api/user/settings

Updates an Arkime user’s settings.

Returns:

Name Type Description
success boolean Whether the update user settings operation was successful.
text string The success/error message to (optionally) display to the user.

/user/state/:name API

GET - /api/user/state/:name

Retrieves a user table state object. These are used to save the states of tables within the UI (sessions, files, stats, etc).

Returns:

Name Type Description
tableState object The table state requested.

/user/state/:name API

POST - /api/user/state/:name

Updates or creates a user table state object. These are used to save the states of tables within the UI (sessions, files, stats, etc).

Returns:

Name Type Description
success boolean Whether the operation was successful.
text string The success/error message to (optionally) display to the user.

/user/config/:page API

GET - /api/user/config/:page

Fetches the configuration/layout information for a UI page for a user.

Returns:

Name Type Description
  object config The configuration data for the page

/views API

GET - /api/views

Retrieves Arkime views that a user can view.

Returns:

Name Type Description
views Array.<ArkimeView> A list of views a user has configured or has been shared.

/view API

POST - /api/view

Creates an Arkime view.

Returns:

Name Type Description
success boolean Whether the create view operation was successful.
text string The success/error message to (optionally) display to the user.
view ArkimeView The new view data.

/view/:id API

DELETE - /api/view/:id

Deletes an Arkime view.

Returns:

Name Type Description
success boolean Whether the delete view operation was successful.
text string The success/error message to (optionally) display to the user.

/view/:id API

PUT - /api/view/:id

Updates an Arkime view.

Returns:

Name Type Description
success boolean Whether the update view operation was successful.
text string The success/error message to (optionally) display to the user.

/dashboards/system API

GET - /api/dashboards/system

The dashboards Arkime ships and the ones an admin added to a dashboardsDir directory (*.dashboard.json files). They are read only and visible to every user; the Arkime tab opens one from ?dashboard=.

Returns:

Name Type Description
data array The dashboards, each shaped like a summaryConfig
shareable list entry: { id, type, name, description, data, system: true, canEdit: false, canDelete: false }    

ArkimeQuery Type

A query to be run periodically that can perform actions on sessions that match the queries. The query runs against sessions delayed by 90 seconds to make sure all updates have been completed for that session.

Parameters:

Param Type Default Description
name string   The name of the query
enabled boolean   Whether the query is enabled. If enabled, the query will run every 90 seconds.
lpValue number   The last packet timestamp that was searched. Used to query for the next group of sessions to search. Format is seconds since Unix EPOCH.
lastRun number   The time that the query was last run. Format is seconds since Unix EPOCH.
count number   The count of total sessions that have matched this query.
lastCount number   The count of sessions that have matched this query during its last run.
query string   The search expression to apply when searching for sessions.
action string "tag" The action to perform when sessions have matched. “tag” or “forward:clusterName”.
creator string   The id of the user that created this query.
tags string   A comma separated list of tags to add to each session that matches this query.
notifier string   A comma separated list of notifier IDs to alert when there are matches for this query.
lastNotified number   The time that this query last sent a notification to the notifiers. Only notifies every 10 minutes. Format is seconds since Unix EPOCH.
lastNotifiedCount number   The count of sessions that matched since the last notification was sent.
description string   The description of this query.
created number   The time that this query was created. Format is seconds since Unix EPOCH.
lastToggled number   The time that this query was enabled or disabled. Format is seconds since Unix EPOCH.
lastToggledBy string   The user who last enabled or disabled this query.
users string   The list of userIds who have access to use this query.
roles string   The list of roles who have access to use this query.
editRoles string   The list of roles who have access to edit this query.

History Type

The history object to describe user client requests.

Parameters:

Param Type Description
uiPage string The client application page that the user accessed to make the request.
userId string The ID of the user that made the request.
method string The HTTP method that the request used.
api string The API endpoint of the request.
expression string The sessions search expression used in the request.
view ArkimeView The view applied to the request.
timestamp number The time that the request was made. Format is seconds since Unix EPOCH.
range number The date range of the request. Range is described in hours, -1 means all.
query string The query parameters of the request.
queryTime number The time it took for the response to be returned after the request was issued.
recordsTotal number The total number of items in the data set.
recordsFiltered number The number of items returned from searching the dataset (before paging).
recordsReturned number The number of items returned in the response (after paging).
body object The request body.
forcedExpression string The expression applied to the search as a result of a user’s forced expression. Only visible to admins, normal users cannot see their forced expressions.

Hunt Type

A packet search job that allows users to search within session packets for text.

Parameters:

Param Type Description
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section

Properties

Name Type Description
userId string The ID of the user that created the hunt.
status string The status of the hunt. Options include: queued - The hunt is queued to search packets once the currently running hunt has finished. running - The hunt is currently searching packets. paused - The hunt is paused, either by a user or by error. finished - The hunt has searched all requested sessions.
name string The name of the hunt (not unique).
size number The number of packets to search within each session.
search string The search text to search for within packets.
searchType string What type of search the text is. Options include: ascii - search for case insensitive ascii text. asciicase - search for case sensitive ascii text. hex - search for hex text. regex - search for text using safe regex. hexregex - search for text using safe hex regex.
src boolean Whether to search the source packets. Must search src or dst or both.
dst boolean Whether to search the destination packets. Must search src or dst or both.
type string Whether to search raw or reassembled packets.
matchedSessions number How many sessions contain packets that match the search text.
searchedSessions number How many sessions have had their packets searched.
totalSessions number The number of sessions to search.
lastPacketTime number The date of the last packet of the last searched session. Used to query for the next chunk of sessions to search. Format is milliseconds since Unix EPOCH.
created number The time that the hunt was created. Format is seconds since Unix EPOCH.
lastUpdated number The time that the hunt was last updated in the DB. Used to only update every 2 seconds. Format is seconds since Unix EPOCH.
started number The time that the hunt was started (put into running state). Format is seconds since Unix EPOCH.
errors array The list of errors that a hunt encountered. A hunt error includes: value - The error text to display to the user. time - The time the error was encountered. node - The Arkime node that the hunt was searching sessions for when the error occurred.
notifier string The optional notifier name to fire when there is an error, or there are matches (every 10 minutes), or when the hunt is complete.
unrunnable boolean Whether an error has rendered the hunt unrunnable.
failedSessionIds array The list of sessions that have failed to be searched. Used to run the search against them again once the rest of the hunt is complete.
users array The list of users to be added to the hunt so they can view the results.
removed boolean Whether the hunt name and ID fields have been removed from the matched sessions.

SessionsQuery Parameter List

Many Arkime Session requests support a standard set of query parameters. These parameters can be used to filter and sort the returned data. For large queries, prefer the POST method to avoid URL length limits, which allows you to include parameters in the request body (these override any URL duplicates). Ensure parameters with special characters are URL encoded when placed in the URL.

Parameters:

Param Type Default Description
date number 1 Perform the search from a specified number of hours ago until the present moment, where ‘-1’ indicates searching all available data.
expression string   The search expression string, ensure URL encoded
facets number 0 1 = include the aggregation information for maps and timeline graphs.
interval string "auto" The timeline graph’s bucket size: ‘second’, ‘minute’, ‘hour’, ‘day’, ‘week’, or ‘auto’ to pick one from the time range. ‘hourOfWeek’ buckets by the hour and folds the buckets into a week, so each Histo series is [[slot, value], ...] with slot 0 = Monday 00:00 .. 167 = Sunday 23:00 in the timezone parameter's zone, and the graph carries hourOfWeek: true.
timezone string "UTC" With interval=hourOfWeek, the IANA zone name (eg America/New_York) the hours are folded in; an unknown zone is UTC.
length number 100 The number of items to return, beginning at start parameter, max is 2,000,000
start number 0 The entry to start at for pagination purposes.
startTime number   If the date parameter is not set, this is the start time of data to return. Format is seconds since Unix EPOCH.
stopTime number   If the date parameter is not set, this is the stop time of data to return. Format is seconds since Unix EPOCH.
view string   The Arkime view name to apply before the expression.
order string   Comma separated list of db field names to sort on. Data is sorted in order of the list supplied. Optionally can be followed by :asc or :desc for ascending or descending sorting.
fields string   Comma separated list of db field names to return. Default is ipProtocol, rootId, totDataBytes, client.bytes, server.bytes, firstPacket, lastPacket, source.ip, source.port, destination.ip, destination.port, network.packets, source.packets, destination.packets, network.bytes, source.bytes, destination.bytes, node, http.uri, source.geo.country_iso_code, destination.geo.country_iso_code, email.subject, email.src, email.dst, email.filename, dns.host, cert, irc.channel, http.xffGEO
bounding string "last" Query sessions based on different aspects of a session’s time. Options include: ‘first’ - First Packet: the timestamp of the first packet received for the session. ‘last’ - Last Packet: The timestamp of the last packet received for the session. ‘both’ - Bounded: Both the first and last packet timestamps for the session must be inside the time window. ‘either’ - Session Overlaps: The timestamp of the first packet must be before the end of the time window AND the timestamp of the last packet must be after the start of the time window. ‘database’ - Database: The timestamp the session was written to the database. This can be up to several minutes AFTER the last packet was received.
strictly boolean false When set the entire session must be inside the date range to be observed, otherwise if it overlaps it is displayed. Overwrites the bounding parameter, sets bounding to ‘both’

Shortcut Type

The shortcut object to store lists of values that can be used in search queries.

Parameters:

Param Type Default Description
userId string   The ID of the user that created the shortcut.
name string   The name of the shortcut.
description string   The description of the shortcut to display to users.
number Array.<number>   A list of number values to use as the shortcut value. A shortcut must contain a list of numbers, strings, or ips.
ip Array.<string>   A list of ip values to use as the shortcut value. A shortcut must contain a list of numbers, strings, or ips.
string Array.<string>   A list of string values to use as the shortcut value. A shortcut must contain a list of numbers, strings, or ips.
users string   A list of userIds that have access to this shortcut.
roles Array.<string>   A list of Arkime roles that have access to this shortcut.
editRoles Array.<string>   A list of Arkime roles that have edit access to this shortcut.
locked boolean false Whether the shortcut is locked and must be updated using the db.pl script (can’t be updated in the web application user interface).

ESHealth Type

The OpenSearch/Elasticsearch cluster health status and information.

Properties

Name Type Description
active_primary_shards number The number of active primary shards.
active_shards number The total number of active primary and replica shards.
active_shards_percent_as_number number The ratio of active shards in the cluster expressed as a percentage.
cluster_name string The name of the arkime cluster
delayed_unassigned_shards number The number of shards whose allocation has been delayed by the timeout settings.
initializing_shards number The number of shards that are under initialization.
molochDbVersion number The arkime database version
number_of_data_nodes number The number of nodes that are dedicated data nodes.
number_of_in_flight_fetch number The number of unfinished fetches.
number_of_nodes number The number of nodes within the cluster.
number_of_pending_tasks number The number of cluster-level changes that have not yet been executed.
relocating_shards number The number of shards that are under relocation.
status string Health status of the cluster, based on the state of its primary and replica shards. Statuses are: “green” - All shards are assigned. “yellow” - All primary shards are assigned, but one or more replica shards are unassigned. If a node in the cluster fails, some data could be unavailable until that node is repaired. “red” - One or more primary shards are unassigned, so some data is unavailable. This can occur briefly during cluster startup as primary shards are assigned.
task_max_waiting_in_queue_millis number The time expressed in milliseconds since the earliest initiated task is waiting for being performed.
timed_out boolean If false the response returned within the period of time that is specified by the timeout parameter (30s by default).
unassigned_shards number The number of shards that are not allocated.
version string the elasticsearch version number
_timeStamp number timestamps in ms from unix epoch

ArkimeView Type

A database view that can be applied to any search.

Parameters:

Param Type Description
name string The name of the view.
expression string The search expression to filter sessions.
sessionsColConfig ArkimeColumnConfig The Sessions column configuration to apply to the Sessions table when applying the view.
user string The user ID of the user who created the view.
users string The list of userIds who have access to use this view.
roles Array.<string> The list of roles who have access to use this view.
editRoles Array.<string> The list of roles who have access to edit this view.