Skip to content
Try the API
Try the API

Track jobs

Every hunt, backup, restore, deployment and maintenance task in Elastio runs as a job. This guide shows how to find jobs, filter them by kind and status, and poll one until it finishes, for example after you run a policy on demand or recover a finding.

Two kinds of job, one catalog

Section titled “Two kinds of job, one catalog”

Jobs come from two sources:

  • Cloud Connector jobs run against assets: hunts, backups, inventory and region stacks. They have a human-readable ID (cc_job_id, for example j-01m09zvyyfcgx4ynp40x4e4rej), asset details, and linked hunt and backup IDs.
  • Tenant jobs are deployment and system work that isn’t tied to an asset.

GET /gateway/api/v1/jobs merges both into one newest-first list and tags each row with source (cloud-connector or tenant). Use /jobs/cloud-connector or /jobs/tenant when you only want one source and need its full row shape.

All the list, count and group endpoints require startDate and endDate (YYYY-MM-DD). They use camelCase token pagination: pageSize (1–100, default 10) and pageToken. Pass back data.pagination.next_page_token as pageToken to get the next page. See Pagination.

Count jobs by kind

Section titled “Count jobs by kind”
GET
/gateway/api/v1/jobs/countCount Cloud Connector and tenant jobs in the unified catalog
Try it

The count call takes the same filters as the list. It returns the total, the share from each source, and counts for three groups: hunt (all hunt work), deployment and system. Every parent job falls into exactly one of the three, so they add up to total_count.

Terminal window
curl "https://acme.app.elastio.com/gateway/api/v1/jobs/count?startDate=2026-10-05&endDate=2026-10-12&statuses=failed" \
  -H "Authorization: Bearer $ELASTIO_TOKEN"

Example response:

{
  "status": 200,
  "data": {
    "total_count": 9,
    "cloud_connector_count": 8,
    "tenant_count": 1,
    "hunt_count": 6,
    "deployment_count": 1,
    "system_count": 2
  },
  "cached": false,
  "expiresInMs": null,
  "message": "…"
}

Discover valid filter values

Section titled “Discover valid filter values”
GET
/gateway/api/v1/jobs/cloud-connector/filtersGet Cloud Connector job filters
Try it

Job kinds aren’t a fixed list in the spec, so read the values your tenant actually has from the filters endpoints. The cloud connector filters return the available kinds, statuses, assets, cloud_connectors, asset_accounts and trigger_sources. GET /gateway/api/v1/jobs/tenant/filters returns the same kind of data for tenant jobs.

Job statuses are scheduled, starting, in_progress, failed, succeeded and aborted.

Terminal window
curl "https://acme.app.elastio.com/gateway/api/v1/jobs/cloud-connector/filters" \
  -H "Authorization: Bearer $ELASTIO_TOKEN"

Example response (trimmed):

{
  "status": 200,
  "data": {
    "kinds": [ "…" ],
    "statuses": [ "scheduled", "starting", "in_progress", "failed", "succeeded", "aborted" ],
    "cloud_connectors": [
      { "id": "…", "deployment": "cloud_connector", "aws_account_id": "123456789012", "aws_region": "us-east-1" }
    ],
    "trigger_sources": [ "guardduty", "threat-hunt" ],
    …
  },
  "cached": true,
  "message": "…"
}

List failed jobs from the last week

Section titled “List failed jobs from the last week”
GET
/gateway/api/v1/jobsList Cloud Connector and tenant jobs in one catalog
Try it

Useful filters (all comma-separated where they take lists):

Parameter What it does
kinds Job kinds, matched against each source’s own kind
statuses Job statuses, for example failed,aborted
kindScope hunt, deployment or system, the same groups as the count call
platform aws or azure
assetIds, assetAccountIds, triggerSources, policy_id Asset-based filters. They exclude tenant jobs, which have no asset.
jobId Case-insensitive prefix match on the human-readable cc_job_id
Terminal window
curl -G "https://acme.app.elastio.com/gateway/api/v1/jobs" \
  -H "Authorization: Bearer $ELASTIO_TOKEN" \
  --data-urlencode "startDate=2026-10-05" \
  --data-urlencode "endDate=2026-10-12" \
  --data-urlencode "statuses=failed,aborted" \
  --data-urlencode "pageSize=100"

Example response (trimmed):

{
  "status": 200,
  "data": {
    "jobsList": [
      {
        "source": "cloud-connector",
        "id": "9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
        "cc_job_id": "j-01m09zvyyfcgx4ynp40x4e4rej",
        "kind": "…",
        "status": "failed",
        "status_message": "…",
        "error_message": "…",
        "finalized": true,
        "target_asset_details": { "id": "2b7e9c1d-3f4a-4b5c-8d6e-7f8091a2b3c4", "kind": "s3", "aws_id": "production-data-bucket", "account_id": "123456789012", "region": "us-east-1" },
        "policies": [ { "id": "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", "name": "prod-s3-scan" } ],
        "started_at": "2026-10-11T02:00:05Z",
        "finished_at": "2026-10-11T02:04:41Z",
        "duration_sec": 276,
        "created_at": "2026-10-11T02:00:00Z",
        "updated_at": "2026-10-11T02:04:41Z",
        "tenant_name": "acme",
        "childrenList": [ … ],
        …
      }
    ],
    "pagination": { "next_page_token": null, "prev_page_token": null, "total_count": 1 }
  },
  "cached": false,
  "expiresInMs": null,
  "message": "…"
}

To count jobs per asset or per policy instead of listing them, call GET /gateway/api/v1/jobs/groups?group_by=asset (or policy) with the same filters. Then load one group’s jobs by passing its key as assetIds or policy_id.

Poll a cloud connector job until it finishes

Section titled “Poll a cloud connector job until it finishes”
GET
/gateway/api/v1/jobs/cloud-connector/{jobId}Get Cloud Connector job by id
Try it

jobId is the parent job UUID (the id field, not cc_job_id). The spec types the job in data as a free-form object. In the cloud connector list, a job has status (see the values above) and finalized, which is true once the job has finished and won’t be retried. The poller below reads those fields defensively. Poll at a moderate interval, as the example does.

Terminal window
curl "https://acme.app.elastio.com/gateway/api/v1/jobs/cloud-connector/9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a" \
  -H "Authorization: Bearer $ELASTIO_TOKEN"

Example response (trimmed):

{
  "status": 200,
  "data": {
    "id": "9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
    "status": "succeeded",
    "finalized": true,
    …
  },
  "message": "…"
}

When a hunt job finishes, GET /gateway/api/v1/jobs/cloud-connector/{jobId}/scans returns its hunts. Each one has a status (good or bad), a type (direct or backup), a threat_count (the number of findings), and the target assets.

All endpoints

Section titled “All endpoints”

Jobs

17 operations in the reference →