Discovery Jobs API

Discovery jobs are how Infracast populates and updates your infrastructure graph. A discovery job runs one or more plugins against your cloud accounts, Kubernetes clusters, or on-premises systems, collecting resource data and building the node/edge graph. After discovery completes, the audit engine automatically re-evaluates all compliance rules.

---

Endpoints

Method	Path	Description	Permission
GET	/api/v1/tenants/{tenantID}/jobs	List discovery jobs	jobs:read
POST	/api/v1/tenants/{tenantID}/jobs	Create and start a job	jobs:create
GET	/api/v1/tenants/{tenantID}/jobs/{jobID}	Get job status/details	jobs:read
DELETE	/api/v1/tenants/{tenantID}/jobs/{jobID}	Cancel a running job	jobs:cancel
GET	/api/v1/tenants/{tenantID}/jobs/{jobID}/stream	Stream job logs	jobs:read

---

Create a Discovery Job

POST /api/v1/tenants/{tenantID}/jobs

Creates and immediately starts a discovery job.

Request Body

{
  "name": "AWS Full Discovery — us-east-1",
  "plugins": ["aws"],
  "credential_id": "cred-aws-prod-abc123",
  "config": {
    "regions": ["us-east-1", "us-west-2"],
    "services": ["ec2", "s3", "iam", "rds", "lambda", "eks"],
    "account_id": "123456789012"
  }
}

Request Fields

Field	Type	Required	Description
name	string	✅	Human-readable job name
plugins	array	✅	Plugin IDs to run (see Plugin List)
credential_id	string	✅	Credential to use for discovery
config	object	❌	Plugin-specific configuration
config.regions	array	❌	AWS regions to scan (default: all)
config.services	array	❌	AWS services to scan (default: all)

Example Request

curl -X POST https://api.infracast.io/api/v1/tenants/acme-corp/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Full AWS Discovery",
    "plugins": ["aws"],
    "credential_id": "cred-aws-prod-abc123",
    "config": {
      "regions": ["us-east-1", "us-east-2"],
      "services": ["ec2", "s3", "iam", "rds", "eks", "cloudtrail"]
    }
  }'

Response

{
  "id": "job-abc123def456",
  "tenant_id": "acme-corp",
  "name": "Full AWS Discovery",
  "status": "running",
  "plugins": ["aws"],
  "credential_id": "cred-aws-prod-abc123",
  "config": {
    "regions": ["us-east-1", "us-east-2"],
    "services": ["ec2", "s3", "iam", "rds", "eks", "cloudtrail"]
  },
  "started_at": "2024-03-16T10:00:00Z",
  "created_at": "2024-03-16T10:00:00Z"
}

---

Get Job Status

GET /api/v1/tenants/{tenantID}/jobs/{jobID}

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.infracast.io/api/v1/tenants/acme-corp/jobs/job-abc123def456"

Response

{
  "id": "job-abc123def456",
  "tenant_id": "acme-corp",
  "name": "Full AWS Discovery",
  "status": "completed",
  "plugins": ["aws"],
  "stats": {
    "nodes_discovered": 1247,
    "nodes_updated": 312,
    "nodes_removed": 8,
    "edges_created": 4820,
    "findings_created": 34,
    "findings_resolved": 12,
    "duration_seconds": 187
  },
  "started_at": "2024-03-16T10:00:00Z",
  "completed_at": "2024-03-16T10:03:07Z",
  "created_at": "2024-03-16T10:00:00Z"
}

Job Status Values

Status	Description
pending	Job created, not yet started
running	Discovery in progress
completed	Discovery completed successfully
failed	Discovery failed (see error field)
cancelled	Job was cancelled before completion

---

List Discovery Jobs

GET /api/v1/tenants/{tenantID}/jobs

# List recent jobs
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.infracast.io/api/v1/tenants/acme-corp/jobs?per_page=10&sort=-created_at"

{
  "items": [
    {
      "id": "job-abc123def456",
      "name": "Full AWS Discovery",
      "status": "completed",
      "plugins": ["aws"],
      "stats": { "nodes_discovered": 1247, "duration_seconds": 187 },
      "started_at": "2024-03-16T10:00:00Z",
      "completed_at": "2024-03-16T10:03:07Z"
    },
    {
      "id": "job-xyz789uvw012",
      "name": "Kubernetes Scan — prod-cluster",
      "status": "failed",
      "plugins": ["kubernetes"],
      "error": "Connection refused: kubeconfig context 'prod-cluster' unreachable",
      "started_at": "2024-03-15T09:00:00Z",
      "completed_at": "2024-03-15T09:00:15Z"
    }
  ],
  "total": 47,
  "page": 1,
  "per_page": 10
}

---

Stream Job Logs

Get real-time log output from a running discovery job (Server-Sent Events):

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.infracast.io/api/v1/tenants/acme-corp/jobs/job-abc123def456/stream"

# Output:
data: {"ts":"2024-03-16T10:00:01Z","level":"info","msg":"Starting AWS plugin for account 123456789012"}
data: {"ts":"2024-03-16T10:00:05Z","level":"info","msg":"Discovered 342 EC2 instances in us-east-1"}
data: {"ts":"2024-03-16T10:00:12Z","level":"info","msg":"Discovered 67 S3 buckets"}
data: {"ts":"2024-03-16T10:00:45Z","level":"info","msg":"Discovered 234 IAM users, 512 IAM roles"}
data: {"ts":"2024-03-16T10:01:20Z","level":"warn","msg":"Skipping service 'glacier': insufficient permissions"}
data: {"ts":"2024-03-16T10:03:07Z","level":"info","msg":"Discovery complete: 1247 nodes, 4820 edges"}

---

Available Plugins

List all available discovery plugins:

GET /api/v1/plugins

Plugin ID	Name	Discovers
aws	Amazon Web Services	EC2, S3, IAM, RDS, Lambda, EKS, CloudTrail, VPC, KMS, and 40+ more
azure	Microsoft Azure	VMs, Storage, SQL, Networking, Entra ID, Key Vault
gcp	Google Cloud Platform	Compute, GCS, Cloud SQL, IAM, GKE, Networking
kubernetes	Kubernetes	Pods, Services, Deployments, RBAC, Namespaces
m365	Microsoft 365	Users, Groups, Applications, Exchange, SharePoint
github	GitHub	Repositories, Actions, Org members
agent	On-Premises Agent	Local systems via installed agent

---

Plugin Configuration Examples

AWS Discovery

{
  "plugins": ["aws"],
  "config": {
    "regions": ["us-east-1", "us-west-2", "eu-west-1"],
    "services": ["ec2", "s3", "iam", "rds", "lambda", "eks", "cloudtrail", "kms", "shield", "config"],
    "role_arn": "arn:aws:iam::123456789012:role/InfracastReadOnly",
    "external_id": "infracast-external-id-abc123"
  }
}

Kubernetes Discovery

{
  "plugins": ["kubernetes"],
  "config": {
    "cluster_name": "prod-eks-cluster",
    "kubeconfig": "base64-encoded-kubeconfig",
    "namespaces": ["default", "production", "monitoring"],
    "include_rbac": true
  }
}

Multi-Plugin Job

{
  "name": "Full Environment Discovery",
  "plugins": ["aws", "kubernetes"],
  "credential_id": "cred-aws-prod",
  "config": {
    "aws": {
      "regions": ["us-east-1"],
      "services": ["ec2", "eks", "iam"]
    },
    "kubernetes": {
      "cluster_name": "prod-eks",
      "include_rbac": true
    }
  }
}

---

Cancel a Job

DELETE /api/v1/tenants/{tenantID}/jobs/{jobID}

Cancels a running job. Any data already discovered is preserved.

---

Scheduling Discovery

Discovery jobs can be scheduled to run automatically:

POST /api/v1/tenants/{tenantID}/reports/schedule
{
  "type": "discovery",
  "job_template": {
    "name": "Daily AWS Scan",
    "plugins": ["aws"],
    "credential_id": "cred-aws-prod-abc123"
  },
  "frequency": "daily",
  "time": "02:00",
  "timezone": "UTC"
}

Best Practice

Schedule discovery at least daily (nightly recommended) to keep your compliance posture current. For regulated environments (FedRAMP, DoD), run discovery before generating monthly ConMon deliverables.

---

Error Handling

Common job failure reasons:

Error	Cause	Fix
insufficient_permissions	IAM role missing required read permissions	Attach ReadOnlyAccess or scoped read policy
invalid_credential	Credentials expired or revoked	Update credential in Settings → Credentials
rate_limited	AWS API rate limit hit	Reduce discovery scope or schedule during off-peak
connection_refused	Kubernetes API unreachable	Verify kubeconfig and network connectivity
node_limit_exceeded	License node limit reached	Upgrade plan or reduce discovery scope

---

Next Steps

• Nodes API — Browse discovered resources
• Findings API — Compliance results from the latest discovery
• Credentials Setup — Configure cloud credentials for discovery