Find assets

Use the search and asset endpoints to build an inventory of everything Elastio protects, find assets with findings or without hunt coverage, and pull the detail and hunt history for a single asset.

Before you begin

• A personal access token with inventory read access. See Authentication.
• Your tenant base URL, for example https://acme.app.elastio.com.

The unified search, the typed searches and the tag endpoints all use token pagination (page_size plus next_page_token or page_token). See Pagination.

Search all assets

The unified search covers every platform and asset type in one list. Filters are comma-separated strings. The spec lists these values:

Parameter	Values
health	infected, at_risk, clean
threat_type	malware, ransomware, filesystem_error, encryption
platform	aws, azure, on_prem, ibm
asset_type	ec2_instance, ebs_volume, s3_bucket, efs_filesystem, fsx_ontap_volume, ova_server, azure_compute_vm, azure_compute_disk, azure_storage_blob_container, azure_storage_file_share, ibm_cos_bucket
scan_coverage	covered, not_covered
last_threat_detected_range	last_hour, last_6_hours, last_day, last_week, last_month
sort_by	HEALTH_ASC/_DESC, PLATFORM_…, SUBSCRIPTION_…, REGION_…, ASSET_TYPE_…, LAST_THREAT_DETECTED_AT_…

page_size is capped at 100. Pass the returned data.pagination.next_page_token as page_token to get the next page.

GET

/gateway/api/v1/search/assetsSearch unified assets across all platforms and types

Try it →

This example lists AWS assets with findings (health=infected), most recent findings first, and follows every page:

cURL

curl -G "https://acme.app.elastio.com/gateway/api/v1/search/assets" \
  -H "Authorization: Bearer $ELASTIO_TOKEN" \
  --data-urlencode "platform=aws" \
  --data-urlencode "health=infected" \
  --data-urlencode "sort_by=LAST_THREAT_DETECTED_AT_DESC" \
  --data-urlencode "page_size=100"

Python

import os, requests

BASE = "https://acme.app.elastio.com"
HEADERS = {"Authorization": f"Bearer {os.environ['ELASTIO_TOKEN']}"}

params = {
    "platform": "aws",
    "health": "infected",
    "sort_by": "LAST_THREAT_DETECTED_AT_DESC",
    "page_size": 100,
}
assets = []
while True:
    resp = requests.get(f"{BASE}/gateway/api/v1/search/assets", headers=HEADERS, params=params, timeout=30)
    resp.raise_for_status()
    data = resp.json()["data"]
    assets.extend(data["assets"])
    token = data["pagination"].get("next_page_token")
    if not token:
        break
    params["page_token"] = token

for a in assets:
    print(a["id"], a["asset_type"], a["asset_name"], a["threat_counts"]["total"])

PowerShell

$Base = "https://acme.app.elastio.com"
$Headers = @{ Authorization = "Bearer $env:ELASTIO_TOKEN" }
$Query = "platform=aws&health=infected&sort_by=LAST_THREAT_DETECTED_AT_DESC&page_size=100"

$Assets = @()
$Token = $null
do {
    $Uri = "$Base/gateway/api/v1/search/assets?$Query"
    if ($Token) { $Uri += "&page_token=$([uri]::EscapeDataString($Token))" }
    $Page = Invoke-RestMethod -Uri $Uri -Headers $Headers
    $Assets += $Page.data.assets
    $Token = $Page.data.pagination.next_page_token
} while ($Token)

$Assets | Select-Object id, asset_type, asset_name, health

Example response (trimmed):

{
  "status": 200,
  "data": {
    "assets": [
      {
        "id": "6f1c2a9e-3b4d-4e8f-9a7b-1c2d3e4f5a6b",
        "health": "infected",
        "asset_name": "i-0abc123def4567890",
        "threat_type": ["ransomware"],
        "threat_counts": { "malware": 0, "ransomware": 2, "filesystem_error": 0, "encryption": 0, "total": 2 },
        "created_at": "2026-03-02T10:14:00Z",
        "updated_at": "2026-10-11T22:05:31Z",
        "last_threat_detected_at": "2026-10-11T21:58:12Z",
        "latest_scans": {
          "malware": "2026-10-11T21:58:12Z",
          "ransomware": "2026-10-11T21:58:12Z",
          "filesystem_check": "2026-10-11T21:58:12Z",
          "encryption": "2026-10-11T21:58:12Z"
        },
        "platform": "aws",
        "subscription": "123456789012",
        "region": "us-east-1",
        "asset_type": "ec2_instance",
        "state": "running",
        "aws_resource_name": "payments-api-01",
        "data_classification_findings": null
      }
    ],
    "pagination": { "next_page_token": "eyJvZmZzZXQiOjEwMH0=", "prev_page_token": "", "total": "37" }
  },
  "cached": false,
  "message": "OK"
}

threat_type is deprecated; read threat_counts instead. pagination.total is returned as a string.

Discover filter values

To populate a picker, or to see which accounts, regions and states actually exist in your tenant, call the filters endpoint with the same query parameters. Each facet comes back as a list of { value, label } pairs.

GET

/gateway/api/v1/search/assets/filtersGet filter options for assets search

Try it →

cURL

curl "https://acme.app.elastio.com/gateway/api/v1/search/assets/filters?platform=aws" \
  -H "Authorization: Bearer $ELASTIO_TOKEN"

Python

resp = requests.get(f"{BASE}/gateway/api/v1/search/assets/filters", headers=HEADERS, params={"platform": "aws"}, timeout=30)
resp.raise_for_status()
facets = resp.json()["data"]
print([r["value"] for r in facets["region"]])

PowerShell

$Facets = (Invoke-RestMethod -Uri "$Base/gateway/api/v1/search/assets/filters?platform=aws" -Headers $Headers).data
$Facets.region | ForEach-Object { $_.value }

{
  "status": 200,
  "message": "OK",
  "data": {
    "health": [{ "value": "infected", "label": "Infected" }, { "value": "clean", "label": "Clean" }],
    "subscription": [{ "value": "123456789012", "label": "123456789012", "platform": "aws" }],
    "region": [{ "value": "us-east-1", "label": "us-east-1" }, { "value": "eu-west-1", "label": "eu-west-1" }],
    "asset_type": [{ "value": "ec2_instance", "label": "EC2 instance" }],
    "…": "…"
  }
}

Search one asset type

Typed searches return fields specific to one kind of asset, such as AMI details and VPC for EC2 instances or object counts for S3 buckets. They use page_size, next_page_token and prev_page_token, and return the list in data.assetsList. Available typed searches:

Asset type	Endpoint	Type-specific filters
EC2 instances	/gateway/api/v1/search/ec2_instances	instance_states, vpcIds, scan_sources
EBS volumes	/gateway/api/v1/search/ebs_volumes	volume_states, availability_zones, scan_sources
S3 buckets	/gateway/api/v1/search/s3_buckets	bucket_states, vpc_ids
EFS file systems	/gateway/api/v1/search/efs_filesystems	filesystem_states
FSx for ONTAP volumes	/gateway/api/v1/search/fsx_volumes	volume_states, fsx_file_system_ids, svm_ids, ontap_volume_names
Generic hosts	/gateway/api/v1/search/generic_hosts	hostname
OVA servers	/gateway/api/v1/search/ova_servers	account_ids, backup_providers

The AWS searches also accept account_ids, regions, health, backup_coverage and scan_coverage (covered or not_covered).

GET

/gateway/api/v1/search/ec2_instancesSearch EC2 instances

Try it →

This example finds running EC2 instances in one account that no hunt policy covers:

cURL

curl -G "https://acme.app.elastio.com/gateway/api/v1/search/ec2_instances" \
  -H "Authorization: Bearer $ELASTIO_TOKEN" \
  --data-urlencode "account_ids=123456789012" \
  --data-urlencode "instance_states=running" \
  --data-urlencode "scan_coverage=not_covered" \
  --data-urlencode "page_size=50"

Python

params = {
    "account_ids": "123456789012",
    "instance_states": "running",
    "scan_coverage": "not_covered",
    "page_size": 50,
}
resp = requests.get(f"{BASE}/gateway/api/v1/search/ec2_instances", headers=HEADERS, params=params, timeout=30)
resp.raise_for_status()
for inst in resp.json()["data"]["assetsList"]:
    print(inst["aws_id"], inst["aws_region"], inst["health"])

PowerShell

$Uri = "$Base/gateway/api/v1/search/ec2_instances?account_ids=123456789012&instance_states=running&scan_coverage=not_covered&page_size=50"
(Invoke-RestMethod -Uri $Uri -Headers $Headers).data.assetsList | Select-Object aws_id, aws_region, health

{
  "status": 200,
  "data": {
    "total": "3",
    "assetsList": [
      {
        "id": "0b7e9d4c-2f1a-4c3b-8e5d-6a7b8c9d0e1f",
        "aws_id": "i-0abc123def4567890",
        "arn": "arn:aws:ec2:us-east-1:123456789012:instance/i-0abc123def4567890",
        "aws_account_id": "123456789012",
        "aws_region": "us-east-1",
        "state": "running",
        "health": "at_risk",
        "tags": [{ "key": "Environment", "value": "prod" }],
        "ebs_ids": ["vol-0123456789abcdef0"],
        "aws_vpc_id": "vpc-0a1b2c3d",
        "os_kind": "Linux/UNIX",
        "last_scan": null,
        "…": "…"
      }
    ],
    "pagination": { "next_page_token": "", "prev_page_token": "" },
    "cached": false
  },
  "message": "OK"
}

For a quick headcount per type, GET /gateway/api/v1/assets_count returns ebs, ec2, efs, s3, server and fsx_volumes totals in data.

Tip

The typed searches also define tags and exclude_tags as arrays of {key, value} objects, but the spec does not say how to encode them in the query string. To filter by tag, use the unified v2 asset list (GET /gateway/api/v2/assets?tags=[{"key":"Environment","value":"prod"}]), which documents a JSON-array encoding.

Inspect one asset

Once you have an asset ID, read its current state. The v2 asset endpoint returns health, per-kind finding counts, latest hunt times, tags, effective policy coverage, the most recent clean backup and, for virtual machines, attached volumes and disks.

GET

/gateway/api/v2/assets/{assetId}Get a single live inventory asset by ID

Try it →

cURL

curl "https://acme.app.elastio.com/gateway/api/v2/assets/6f1c2a9e-3b4d-4e8f-9a7b-1c2d3e4f5a6b" \
  -H "Authorization: Bearer $ELASTIO_TOKEN"

Python

asset_id = "6f1c2a9e-3b4d-4e8f-9a7b-1c2d3e4f5a6b"
resp = requests.get(f"{BASE}/gateway/api/v2/assets/{asset_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
asset = resp.json()["data"]
print(asset["health"], asset["threats"], asset.get("last_clean_backup"))

PowerShell

$AssetId = "6f1c2a9e-3b4d-4e8f-9a7b-1c2d3e4f5a6b"
$Asset = (Invoke-RestMethod -Uri "$Base/gateway/api/v2/assets/$AssetId" -Headers $Headers).data
$Asset | Select-Object asset_name, health, threats, last_clean_backup

{
  "data": {
    "asset_id": "6f1c2a9e-3b4d-4e8f-9a7b-1c2d3e4f5a6b",
    "asset_name": "payments-api-01",
    "asset_kind": "ec2_instance",
    "platform": "aws",
    "platform_details": { "account_id": "123456789012", "region": "us-east-1" },
    "health": "infected",
    "tags": [{ "key": "Environment", "value": "prod" }],
    "threats": { "malware": 0, "ransomware": 2, "encryption": 0, "filesystem_error": 0, "pursuit": 0, "custom": 0 },
    "latest_scans": { "malware": "2026-10-11T21:58:12Z", "ransomware": "2026-10-11T21:58:12Z", "encryption": null, "filesystem_check": "2026-10-11T21:58:12Z", "pursuit": null, "custom": null },
    "os_family": "linux",
    "pursuit_supported": false,
    "excluded_reason": null,
    "last_clean_backup": {
      "backup_id": "2d4e6f80-1a3b-4c5d-8e9f-0a1b2c3d4e5f",
      "kind": "…",
      "timestamp": "2026-10-09T03:00:00Z"
    },
    "policies": [
      {
        "id": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
        "name": "prod-daily",
        "coverage_source": "direct",
        "policy_kind": "scheduled",
        "policy_source": null,
        "scan_types": { "ransomware": true, "malware": true, "encryption_detection": false, "data_classification": false, "hunt": false, "pursuit": false }
      }
    ],
    "attachments": [ { "asset_id": "…", "asset_kind": "ebs_volume", "…": "…" } ]
  }
}

Hunt history for an asset

List the hunt results for an asset. This endpoint uses camelCase pagination (pageSize, pageToken); filter by days, kind, type, backupType or triggerSource.

GET

/gateway/api/v1/assets/{assetId}/scanjobsList hunts for an asset

Try it →

cURL

curl "https://acme.app.elastio.com/gateway/api/v1/assets/6f1c2a9e-3b4d-4e8f-9a7b-1c2d3e4f5a6b/scanjobs?days=30&pageSize=20" \
  -H "Authorization: Bearer $ELASTIO_TOKEN"

Python

resp = requests.get(
    f"{BASE}/gateway/api/v1/assets/{asset_id}/scanjobs",
    headers=HEADERS, params={"days": 30, "pageSize": 20}, timeout=30,
)
resp.raise_for_status()
for job in resp.json()["items"]:
    print(job["job_id"], job["timestamp"], job["health"], [s["kind"] for s in job["scans"]])

PowerShell

$Jobs = Invoke-RestMethod -Uri "$Base/gateway/api/v1/assets/$AssetId/scanjobs?days=30&pageSize=20" -Headers $Headers
$Jobs.items | Select-Object job_id, timestamp, health, backupType

{
  "items": [
    {
      "job_id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
      "scans": [
        {
          "id": "8e7d6c5b-4a3f-4e2d-9c1b-0a9f8e7d6c5b",
          "target": { "id": "6f1c2a9e-3b4d-4e8f-9a7b-1c2d3e4f5a6b", "kind_tag": "asset" },
          "job_id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
          "kind": "ransomware_scan",
          "status": "…",
          "type": "backup",
          "created_at": "2026-10-11T21:40:02Z",
          "updated_at": "2026-10-11T21:58:12Z"
        }
      ],
      "health": "infected",
      "type": "backup",
      "timestamp": "2026-10-11T21:58:12Z",
      "backupType": "AWS Backup"
    }
  ],
  "pagination": { "next_page_token": "…", "prev_page_token": "", "total_count": 14 }
}

To dig into a single hunt result and its findings, see Run a hunt.

Fleet health at a glance

GET /gateway/api/v1/assets/health-summary returns clean_assets, infected_assets and at_risk_assets counts, optionally filtered by platform. An asset is at risk when it has not been hunted or its status is unknown.

Work with tags

The tag endpoints list the tag keys present on your assets and the values recorded for each key, with asset counts. Use them to discover what to filter on before you query assets by tag.

GET

/gateway/api/v2/tagsList distinct asset tag keys

Try it →

GET

/gateway/api/v2/tags/valuesList distinct values for an asset tag key

Try it →

cURL

# Tag keys containing "env"
curl "https://acme.app.elastio.com/gateway/api/v2/tags?search=env" \
  -H "Authorization: Bearer $ELASTIO_TOKEN"

# Values recorded for the Environment key
curl "https://acme.app.elastio.com/gateway/api/v2/tags/values?key=Environment&page_size=100" \
  -H "Authorization: Bearer $ELASTIO_TOKEN"

Python

keys = requests.get(f"{BASE}/gateway/api/v2/tags", headers=HEADERS, params={"search": "env"}, timeout=30)
keys.raise_for_status()
for k in keys.json()["data"]:
    print(k["key"], k["asset_count"], k["value_count"])

values = requests.get(
    f"{BASE}/gateway/api/v2/tags/values", headers=HEADERS,
    params={"key": "Environment", "page_size": 100}, timeout=30,
)
values.raise_for_status()
for v in values.json()["data"]:
    print(v["value"], v["asset_count"])

PowerShell

(Invoke-RestMethod -Uri "$Base/gateway/api/v2/tags?search=env" -Headers $Headers).data
(Invoke-RestMethod -Uri "$Base/gateway/api/v2/tags/values?key=Environment&page_size=100" -Headers $Headers).data

{
  "key": "Environment",
  "total": 3,
  "data": [
    { "value": "prod", "asset_count": 212 },
    { "value": "staging", "asset_count": 48 },
    { "value": null, "asset_count": 2 }
  ],
  "pagination": { "next_page_token": "", "prev_page_token": "" }
}

A null value means the tag is present as a key only. page_size defaults to 10 and is capped at 100 on both tag endpoints.

All endpoints

Search

10 operations in the reference →

• GET/gateway/api/v1/search/ebs_volumesSearch EBS volumes
• GET/gateway/api/v1/search/ec2_instancesSearch EC2 instances
• GET/gateway/api/v1/search/s3_bucketsSearch S3 buckets
• GET/gateway/api/v1/search/efs_filesystemsSearch EFS filesystems
• GET/gateway/api/v1/search/generic_hostsSearch generic hosts
• GET/gateway/api/v1/search/ova_serversSearch OVA servers
• GET/gateway/api/v1/search/fsx_volumesSearch FSx ONTAP volumes
• GET/gateway/api/v1/search/assetsSearch unified assets across all platforms and types
• GET/gateway/api/v1/search/assets/filtersGet filter options for assets search
• GET/gateway/api/v1/assets_countGet assets count

Assets

34 operations in the reference →

• GET/gateway/api/v1/recovery-points/{backupId}/assets/{assetId}/threatsGet findings for an asset in a recovery point
• GET/gateway/api/v1/assets/{assetId}/recovery-points/{backupId}/entities/asset-items/{assetItemId}/threatsGet findings for an asset item in a recovery point
• GET/gateway/api/v1/assets/{assetId}/recovery-points/{backupId}/entitiesGet entities for a specific recovery point
• GET/gateway/api/v1/assets/{assetId}/scanjobs/{scanJobId}/entitiesGet the entities a hunt covered
• GET/gateway/api/v1/scanjobs/{scanJobId}/assets/{assetId}/threatsGet findings for an asset from a hunt
• GET/gateway/api/v1/assets/{assetId}/application-discoveriesGet latest application discovery for an asset
• GET/gateway/api/v1/scanjobs/{scanJobId}/asset-items/{assetItemId}/threatsGet findings for an asset item from a hunt
• GET/gateway/api/v1/assets/{assetId}/recovery-pointsGet asset recovery points
• GET/gateway/api/v1/assets/{assetId}/recovery-points/backup-typesGet backup types from recovery points for an asset
• GET/gateway/api/v1/assets/{assetId}/scanjobsList hunts for an asset
• GET/gateway/api/v1/assets/{assetId}/scanjobs/{scanJobId}Get a hunt for an asset
• GET/gateway/api/v1/assets/{assetId}/scanjobs/backup-typesGet backup types covered by an asset's hunts
• GET/gateway/api/v1/get-filtered-dataGet filtered asset data
• GET/gateway/api/v1/assets/{assetId}/recovery-points/{recoveryPointId}Get recovery point details
• GET/gateway/api/v1/infected-filesList files with findings
• GET/gateway/api/v1/s3-buckets/{awsS3BucketId}/infected-objects/last-clean-versionList S3 objects with findings and their last clean version
• GET/gateway/api/v2/assetsGet list of v2 assets (live inventory)
• GET/gateway/api/v2/assets/{assetId}Get a single live inventory asset by ID
• GET/gateway/api/v2/assets/{assetId}/machine-imageGet a machine image's lineage and derived instances
• GET/gateway/api/v2/assets/{assetId}/recovery-pointsGet asset recovery points (v2)
• GET/gateway/api/v2/assets/filtersGet contextual filter options for v2 assets
• GET/gateway/api/v2/assets/groupsGet v2 asset group summaries
• GET/gateway/api/v2/assets/summaryGet scoped live-asset dashboard summary
• GET/gateway/api/v2/assets/r-rpoGet fleet R-RPO
• GET/gateway/api/v2/policies/summaryGet per-policy live-asset dashboard summaries
• GET/gateway/api/v2/assets/coverage-by-platformGet scoped policy coverage grouped by platform
• GET/gateway/api/v1/assets-listList assets by ids
• GET/gateway/api/v1/assets/health-summaryGet asset health summary
• GET/gateway/api/v1/assets/coverage-summaryGet asset coverage summary
• GET/gateway/api/v1/assets/recovery-assuranceGet recovery assurance data
• GET/gateway/api/v1/assets/encryption-summaryGet asset encryption summary
• GET/gateway/api/v1/assets/storage-vulnerabilityGet storage vulnerability summary
• GET/gateway/api/v1/assets/storage-vulnerability/issuesList storage vulnerability issues
• GET/gateway/api/v1/assets/storage-vulnerability/filtersGet contextual filter options for storage vulnerability issues

Inventory

1 operation in the reference →

• POST/gateway/api/v1/aws/inventory-scansSchedule an AWS inventory refresh

Asset Accounts

1 operation in the reference →

• GET/gateway/api/v1/asset-accountsList asset accounts by connector

Tags

2 operations in the reference →

• GET/gateway/api/v2/tagsList distinct asset tag keys
• GET/gateway/api/v2/tags/valuesList distinct values for an asset tag key