Skip to main content

REST APIs for 24.2.20 and 24.2.10

Explorer Reference

This topic contains properties and examples for working with Explorer.

POST [api_version][org_href] traffic_flows/async_queries

Property

Description

Type

query_name

Name of the query

String

sources

Source labels, workloads, or IP addresses to include or exclude in the search.

The response can contain up to five matching IP addresses.

NOTE: The response returns sources as consumers.

Sources are treated as consumers for the purposes of the request; the response returns the source of an individual flow as src.

Sub-properties:

  • include: Targets that can be included are workloads, labels, or IP addresses identified by their HREF and structured as an array of JSON objects.

    If this property is left empty, then include means consider “ALL” or “ANY” of the object type.

  • exclude: Targets that can be excluded are workloads, labels, or IP addresses identified by their HREF and structured as a JSON array.

    • When IP List is present in the Destination part of a traffic query, traffic from workloads that belong to that IP List will not be returned by default.

      If users want to see that traffic, they need to set exclude_workloads_ from_ip_list_query: false

    • When IP List is present in the Source part of traffic query, traffic to workloads that belong to that IP List will not be returned by default.

      If the user wishes to see that traffic, they need to set

      exclude_workloads_from_ip_ list_query: false

Object

destinations

Target labels, workloads, or IP addresses to include or exclude in the search.

The response returns targets as providers.

Required sub-properties:

  • include: Targets that can be included are workloads, labels, or IP addresses identified by their HREF and structured as an array of JSON objects.

    If this property is left empty, then include means consider “ALL” or “ANY” of the object type.

  • exclude: Targets that can be excluded are workloads, labels, or IP addresses identified by their HREF and structured as JSON.

    If this property is left empty, then exclude means exclude “NONE” of the object types.

Object

services

Services (5-tuple of port/to_port/proto/process/service) to include or exclude. Not all properties of the service subobjects are required.

Required properties:

  • include: List of included services (5-tuple of port/to_port/proto/process/service)

  • exclude: List of excluded services (5-tuple of port/to_port/proto/process/service)",

Properties of the includeand exclude subobjects:

  • port: Port Number (integer 0-65535).

    Also the starting port when specifying a range.

  • to_port: High end of port range inclusive if specifying a range.

    If not specifying a range then don't send this:

  • proto: Protocol number. For the expected proto values see IANA Protocol Numbers.

  • process_name: name of the process

  • windows_service_name: name of the Windows service

policy_decisions

List of policy decisions. Allows you to filter the query based on policy decision:

  • allowed: Allowed traffic.

  • potentially_blocked: Allowed but potentially blocked traffic.

    This type of traffic occurs when a workload VEN is in the test policy state.

  • blocked: Blocked traffic.

  • unknown

Array of strings

boundary_decisions

List of boundary decisions

  • blocked: blocked due to boundary

  • override_deny_rule: overridden deny rule

  • blocked_non_illumio_rule: Deny rule not written by Illumio

Array

max_results

Maximum number of flows to return. Limit is 200,000

Integer

exclude_ workloads_ from_ip_ list_query

Exclude workload traffic when IP List is provided either in the Destination or Source part of the traffic query.

Boolean

data_sources

This property was added in release 24.1 and describes the data sources of the flows to be included or excluded.

  • include: "server", "endpoint", "flowlink", "scanner"

  • exclude: "server", "endpoint", "flowlink", "scanner"

GET [api_version][org_href] traffic_flows/async_queries_download

Property

Description

Type

Req

src

Reference to traffic_flows_endpoint.schema.json

Yes

dst

Reference to traffic_flows_endpoint.schema.json

Yes

service

Reference to traffic_flows_service.schema.json

Yes

num_connections

The number of times this flow was seen

Integer

Yes

policy_decision

Policy decision made

String

Yes

draft_policy_decision

The draft policy decision of the flow (added in release 23.2.10)

String

No

timestamp_range

Timestamp ranges for the flow detected. Required properties are:

first_detected

last_detected

Object

Yes

caps

Reference to rbac_permission_types.schema.json

Yes

client_type

The type of client that reported this flow

String

No

Example Async Explorer Queries

Curl command for POST traffic_flows_async_queries

curl -i -u api_1195cf055cf8a834c:148afd87ecc980900eaf10d6c54e6c0f607b22e0dbf768dd007e51e731096282 https://devtest0.ilabs.io:8443/api/v2/orgs/1/traffic_flows/async_queries -H "Content-Type: application/json" -X POST -d '{"sources":{"include":[[{"workload":{"href":"/orgs/1/workloads/a3ffb374-f6c6-4cce-ac57-642c66f1498f"}}]],"exclude":[]},"destinations":{"include":[[]],"exclude":[]},"services":{"include":[],"exclude":[]},"sources_destinations_query_op":"and","start_date":"2016-01-29T17:04:03.149Z","end_date":"2021-01-29T17:06:03.151Z","policy_decisions":[],"max_results":1000,"query_name":"worklaod test"}'

Response:

 HTTP/1.1 202 Accepted
	content-location: 7734501b-74a2-47a4-9ded-77bf4ceea938
	content-type: application/json
	content-length: 615
	x-request-id: 00c8fa00-dbd8-4a28-a5c7-354fb5ae3886
	cache-control: no-store
	x-frame-options: DENY
	x-xss-protection: 1; mode=block
	x-content-type-options: nosniff
{"status":"queued","href":"/orgs/1/traffic_flows/async_queries/7734501b-74a2-47a4-9ded-77bf4ceea938","created_by":{"href":"/users/1"},"query_parameters":{"sources":{"include":[[{"workload":{"href":"/orgs/1/workloads/a3ffb374-f6c6-4cce-ac57-642c66f1498f"}}]],"exclude":[]},"destinations":{"include":[[]],"exclude":[]},"services":{"include":[],"exclude":[]},"sources_destinations_query_op":"and","start_date":"2016-01-29T17:04:03.149Z","end_date":"2021-01-29T17:06:03.151Z","policy_decisions":[],"max_results":1000,"query_name":"worklaod test"},"created_at":"2021-04-09T20:50:30Z","updated_at":"2021-04-09T20:50:30Z"}

Curl command for GET traffic_flows/async_queries

This query gets the collection of all async jobs for the current user, including anything that was already submitted.

curl -i -u api_1195cf055cf8a834c:148afd87ecc980900eaf10d6c54e6c0f607b22e0dbf768dd007e51e731096282 https://devtest0.ilabs.io:8443/api/v2/orgs/1/traffic_flows/async_queries

Response

HTTP/1.1 200 OK
	content-type: application/json
	content-length: 1510
	x-request-id: fcf065e5-e465-4161-ba98-542182734c38
	cache-control: no-store
	x-frame-options: DENY
	x-xss-protection: 1; mode=block
	x-content-type-options: nosniff
[{"matches_count":1984,"flows_count":1000,"status":"completed","href":"/orgs/1/traffic_flows/async_queries/88675fbd-a88e-44bd-b358-2d6f2fc4f95a","result":"/orgs/1/traffic_flows/async_queries/88675fbd-a88e-44bd-b358-2d6f2fc4f95a/download","created_by":{"href":"/users/1"},"query_parameters":{"sources":{"include":[[{"workload":{"href":"/orgs/1/workloads/a3ffb374-f6c6-4cce-ac57-642c66f1498f"}}]],"exclude":[]},"destinations":{"include":[[]],"exclude":[]},"services":{"include":[],"exclude":[]},"sources_destinations_query_op":"and","start_date":"2016-01-29T17:04:03.149Z","end_date":"2021-01-29T17:06:03.151Z","policy_decisions":[],"max_results":1000,"query_name":"worklaod tesrrrrrt"},"created_at":"2021-04-09T20:50:19Z","updated_at":"2021-04-09T20:50:27Z"},{"matches_count":1984,"flows_count":1000,"status":"completed","href":"/orgs/1/traffic_flows/async_queries/7734501b-74a2-47a4-9ded-77bf4ceea938","result":"/orgs/1/traffic_flows/async_queries/7734501b-74a2-47a4-9ded-77bf4ceea938/download","created_by":{"href":"/users/1"},"query_parameters":{"sources":{"include":[[{"workload":{"href":"/orgs/1/workloads/a3ffb374-f6c6-4cce-ac57-642c66f1498f"}}]],"exclude":[]},"destinations":{"include":[[]],"exclude":[]},"services":{"include":[],"exclude":[]},"sources_destinations_query_op":"and","start_date":"2016-01-29T17:04:03.149Z","end_date":"2021-01-29T17:06:03.151Z","policy_decisions":[],"max_results":1000,"query_name":"worklaod test"},"created_at":"2021-04-09T20:50:30Z","updated_at":"2021-04-09T20:50:32Z"

Curl command for GET traffic_flows/async_queries/:uuid

This query gets a specific job included in the collection.

curl -i -u $KEY:$TOKEN https://devtest0.ilabs.io:8443/api/v2/orgs/1/traffic_flows/async_queries/88675fbd-a88e-44bd-b358-2d6f2fc4f95a

Response

HTTP/1.1 200 OK
	content-type: application/json
	content-length: 756
	x-request-id: f328b845-8542-4b96-a128-43aefdf7ba5a
	cache-control: no-store
	x-frame-options: DENY
	x-xss-protection: 1; mode=block
	x-content-type-options: nosniff
{"matches_count":1984,"flows_count":1000,"status":"completed",
"href":"/orgs/1/hanges for22.4.0 from the Wj/async_queries/88675fbd-a88e-44bd-b358-2d6f2fc4f95a",
"result":"/orgs/1/traffic_flows/async_queries/88675fbd-a88e-44bd-b358-2d6f2fc4f95a/download",
"created_by":{"href":"/users/1"},"query_parameters":{"sources":{"include":[[{"workload":{"href":"/orgs/1/workloads/a3ffb374-f6c6-4cce-ac57-642c66f1498f"}}]],"exclude":[]},"destinations":{"include":[[]],"exclude":[]},"services":{"include":[],"exclude":[]},"sources_destinations_query_op":"and","start_date":"2016-01-29T17:04:03.149Z","end_date":"2021-01-29T17:06:03.151Z","policy_decisions":[],"max_results":1000,"query_name":"worklaod tesrrrrrt"},"created_at":"2021-04-09T20:50:19Z","updated_at":"2021-04-09T20:50:27Z"}

Response for GET traffic_flows/async_queries/:uuid_download

{ 		
   "dst": {
	"ip": "10.244.0.1",
	"workload": {
		"href": "/orgs/1/workloads/35d8efea-f230-4027-a8ee-5f20626c4d21",
		"name": "wl3",
		"labels": [
			{
			"key": "env"reserpine for 
			"href": "/orgs/1/labels/7",
			"value": "Production"
			},
			{
			"key": "loc",
			"href": "/orgs/1/labels/11",
			"value": "Amazon"
			},
			{
			"key": "role",
			"href": "/orgs/1/labels/3",
			"value": "API"
			},
			{
			"key": "B-label",
			"href": "/orgs/1/labels/15",
			"value": "b_label_2"
			}
		],
		"managed": false,
		"os_type": "linux",
		"endpoint": false,
		"hostname": "",
		"enforcement_mode": "visibility_only"
		}
	},
    "src": {
	"ip": "10.0.2.15",
	"workload": {
		"href": "/orgs/1/workloads/fc3801b8-05ec-4954-a957-7f5673123389",
		"name": "wl2",
		"labels": [
		{
			"key": "env",
			"href": "/orgs/1/labels/7",
			"value": "Production"
			},
			{
			"key": "loc",
			"href": "/orgs/1/labels/11",
			"value": "Amazon"
			},
			{
			"key": "role",
			"href": "/orgs/1/labels/3",
			"value": "API"
			}
		],
		"managed": false,
		"os_type": "linux",
		"endpoint": false,
		"hostname": "",
		"enforcement_mode": "visibility_only"
		}
	},
    "caps": [],
    "state": "snapshot",
    "dst_bi": 0,
    "dst_bo": 0,
    "seq_id": 2,
    "network": {
	"href": "/orgs/1/networks/fbeeb98d-4ed6-428d-9f71-69f542bfd8fd",
	"name": "Corporate"
	},
    "service": {
	"port": 3306,
	"proto": 6
	},
    "flow_direction": "outbound",
    "num_connections": 1,
    "policy_decision": "unknown",
    "timestamp_range": {
	"last_detected": "2022-09-01T20:35:22Z",
	"first_detected": "2022-09-01T20:35:22Z"
	}
}
Parameters for Database Usage Metrics

The organization flow Database Usage Metrics has the following required parameters:

Parameters

Description

Type

Required

flows_days

Organization's total number of days of flow data

Integer

Yes

flows_days_limit

Organization's limit on the total number of days of flow data

Limit was increased from 90 to 97

Integer

Yes

flows_oldest_day

Organization's oldest day of flow data (yyyy-mm-dd)

String

No

flows_size_gb

Organization's limit on the total number of gigabytes of flow data

Number

Yes

flows_size_gb_limit

Organization's limit on the total number of gigabytes of flow data

Number

Yes

server

Define the server's total flow data per organization for the total numberof days, limit on the total number of days, oldest days, size in gigabytes, and so on.

Object

No

endpoint

Organization's total number of days of endpoint flow data.

Object

No

backlog

Total gigabytes used to store flow data input files

Object

No

updated_at

Timestamp in UTC when these flow metrics were generated

String, date

No

Parameters for server

Parameters

Description

Type

num_flows_days

Organization's total number of days of the server flow data

Integer

num_flows_days_limit

Organization's limit on the total number of days of server flow data

Integer

flows_oldest_day

Organization's oldest day of server flow data (yyyy-mm-dd)

String, date

flows_size_gb

Organization's limit on the total number of gigabytes of server flow data

Number

flows_size_gb_limit

Organization's limit on the total number of gigabytes of server flow data

Number

num_daily_tables

The number of server daily tables, including FlowLink and Cloud, counted once for each unique day

Number

num_weekly_tables

The number of server weekly tables, including FlowLink and Cloud, counted once for each unique week

Number

Parameters for endpoint

Parameters

Description

Type

num_flows_days

Organization's total number of days of the endpoint flow data

Integer

num_flows_days_limit

Organization's limit on the total number of days of endpoint flow data

Integer

flows_oldest_day

Organization's oldest day of endpoint flow data (yyyy-mm-dd)

String, date

flows_size_gb

Organization's limit on the total number of gigabytes of endpoint flow data

Number

flows_size_gb_limit

Organization's limit on the total number of gigabytes of endpoint flow data

Number

num_daily_tables

The number of endpoint daily tables, counted once for each unique day

Number

num_weekly_tables

The number of endpoint weekly tables, counted once for each unique week

Number

Parameters for backlog

Parameters

Description

Type

total_disk_used_gb

Total gigabytes used to store flow data input files

Number

total_file_count

Total number of flow data input files

Integer

An example response looks such as the following:

{
	"org_id":1,
	"server":{
		"flows_size_gb":2.53228759765625,
		"num_flows_days":95,
		"flows_oldest_day":"2023-02-06",
		"num_daily_tables":7,
		"num_weekly_tables":13,
		"flows_size_gb_limit":26,
		"num_flows_days_limit":90
	},
	"endpoint":{
		"flows_size_gb":0.34337615966796875,
		"num_flows_days":6,
		"flows_oldest_day":"2023-05-11",
		"num_daily_tables":6,
		"num_weekly_tables":0,
		"flows_size_gb_limit":26,
		"num_flows_days_limit":14
	},
	"flows_days":95,
	"flows_size_gb":2.8644485473632812,
	"flows_days_limit":90,
	"flows_oldest_day":"2023-02-06",
	"flows_per_second":0.0,
	"flows_size_gb_limit":26,
	"updated_at":"2023-05-16T22:36:25Z"
}
See also: