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 `include`and `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"
}

REST APIs for 24.5

Explorer Reference

POST [api_version][org_href] traffic_flows/async_queries

GET [api_version][org_href] traffic_flows/async_queries_download

Example Async Explorer Queries

Parameters for Database Usage Metrics

Search results