Skip to main content

API Reference

Complete API reference documentation for the Central Monitoring API.

Contents​

API References​

Browse all available endpoints with detailed schemas, examples, and responses:

Logs​

V1
Deprecation Notice

The V1 logs endpoints (/v1/logs/scroll, /v1/logs/batch, and /v1/logs/batch/status) will be deprecated on March 1, 2026. Please migrate to the V2 endpoints.

POST     /v1/logs/batch

Description: Recommended for queries retrieving > 100,000 logs. Returns a token to access presigned URLs containing batches of logs.

Request Body:

{
  "application": "quasar",
  "app_type": "caas",
  "domain": "example.domain.com",
  "time_range": "now-15m/m",
  "size": 1000,
  "filters": {"status": "error"}
}

Required Fields:

  • application (string): Name of the monitored application. Options: "atr", "klewer", "eventops", "quasar"
  • time_range (string): Time range in OpenSearch format (e.g., 'now-15m/m')

Optional Fields:

  • app_type (string): Type of application environment. Options: "ec2", "caas"
  • domain (string): Domain name of the monitored environment
  • size (integer): Maximum number of results to return per request
  • filters (object): JSON object containing additional key-value filters
  • log_group (string): Log group for EventOps
  • tenant (string): Tenant identifier for EventOps
  • stage (string): Stage identifier for EventOps

Response (200):

{
  "logs": [
    {
      "domain": "example.domain.com",
      "time_range": "now-15m/m"
    }
  ],
  "token": "czpcL1wvY29nb",
  "daily_requests_remaining": 480
}
POST     /v1/logs/batch/urls

Description: Use token from Batch API response to retrieve presigned URLs for S3 buckets containing batches of logs.

Request Body:

{
  "token": "1OTk3LCJpc3MiOi"
}

Required Fields:

  • token (string): Access token for batch log retrieval

Response (200):

{
  "presigned_urls": [
    {
      "presigned_url": "https://cm-api-logs-prod.s3.amazonaws.com/logs-domain-name?AWSAccessKeyId=...",
      "time_range": "string",
      "ready": true,
      "status": "completed"
    }
  ]
}
POST     /v1/logs/scroll

Description: Recommended for queries retrieving < 100,000 logs. Retrieve logs using cursor-based pagination with the returned scrollId.

Request Body:

{
  "application": "atr",
  "app_type": "caas",
  "domain": "example.domain.com",
  "time_range": "now-15m/m",
  "size": 1000,
  "filters": {"message": "cluster down"}
}

Required Fields:

  • application (string): Name of the monitored application. Options: "atr", "klewer", "eventops", "quasar"
  • time_range (string): Time range in OpenSearch format (e.g., 'now-15m/m')

Optional Fields:

  • app_type (string): Type of application environment. Options: "ec2", "caas"
  • domain (string): Domain name of the monitored environment
  • size (integer): Maximum number of results to return per request
  • filters (object): JSON object containing additional key-value filters
  • scroll_id (string): Identifier used for paginated scrolling through large datasets
  • log_group (string): Log group for EventOps
  • tenant (string): Tenant identifier for EventOps
  • stage (string): Stage identifier for EventOps

Response (200):

{
  "logs": [
    {
      "domain": "example.domain.com",
      "time_range": "now-15m/m"
    }
  ],
  "scroll_id": "DXF1ZXJ5QW5vbmU=",
  "has_more": true,
  "daily_requests_remaining": 480
}
V2
POST     /v2/logs/scroll

Description: Recommended for queries retrieving < 100,000 logs. Retrieve logs using cursor-based pagination with the returned scroll_id.

Request Body (EC2/Kubernetes):

{
  "application": "atr",
  "app_type": "kubernetes",
  "start_time": "2026-01-19T00:00:00Z",
  "end_time": "2026-01-19T23:59:59Z",
  "size": 100,
  "domain": ["domain1.com", "domain2.com"],
  "fields": ["timestamp", "message", "level"]
}

Request Body (Serverless):

{
  "application": "eventops",
  "app_type": "serverless",
  "start_time": "2026-01-19T00:00:00Z",
  "end_time": "2026-01-19T23:59:59Z",
  "size": 100,
  "log_group": ["*"],
  "tenant": ["tenant1"],
  "stage": ["prod"],
  "fields": ["@timestamp", "logLevel", "message", "request.user_id", "request.endpoint", "response.status_code"],
  "filters": [
    {"exists": {"field": "user.id"}}
  ]
}

Request Body (Pagination):

{
  "scroll_id": "previous_scroll_id_here"
}

Required Fields (Initial Request):

  • application (string): Name of the monitored application. Options: "atr", "klewer", "eventops", "quasar"
  • start_time (string): Start time in ISO 8601 format (e.g., "2026-01-19T00:00:00Z" or "2026-01-19T00:00:00.000Z")
  • end_time (string): End time in ISO 8601 format
  • app_type (string): Application type. Options: "ec2", "kubernetes", "serverless"
  • size (integer): Number of results to return (must be > 0)

Plus these depending on app_type:

  • For serverless (requires application="eventops"):
    • log_group (array): List of log groups or ["*"] for all
    • tenant (array): List of tenants or ["*"] for all
    • stage (array): List of stages or ["*"] for all
  • For ec2/kubernetes:
    • domain (array): List of domain names or ["*"] for all

Optional Fields:

  • filters (array): List of OpenSearch filter objects to apply. See OpenSearch Query DSL for full syntax. Supported filter types:
    • term - Exact match on a field
    • terms - Match any of multiple values
    • range - Numeric or date range queries
    • exists - Check if a field exists
    • bool - Combine filters with nested logic (must, should, must_not)
    • match / match_phrase - Full-text search
  • fields (array): List of fields to include in response (if not provided, all fields are included)
  • scroll_id (string): For pagination (when provided, only this field is required and all others become optional)

Special Rules:

  • App Type Restrictions:
    • serverless → must use application="eventops" + requires log_group, tenant, stage
    • ec2/kubernetes → cannot use application="eventops" + requires domain
  • Wildcard Usage:
    • When using "*" in arrays, it must be the only element: ["*"]
    • Cannot mix wildcard with other values: ["*", "something"]
  • Scroll ID Requests:
    • If scroll_id is provided, all other fields become optional
    • Used for pagination to get next batch of results

Sample Response (200):

{
  "data": {
    "logs": [
      {
        "_index": "logs-application-2026-01",
        "_id": "abc123xyz",
        "_score": 1.0,
        "_source": {
          "...": "Log content varies by application"
        }
      },
      {
        "_index": "logs-application-2026-01",
        "_id": "def456uvw",
        "_score": 1.0,
        "_source": {
          "...": "Log content varies by application"
        }
      }
    ],
    "count": 3595
  },
  "meta": {
    "api_version": "v2",
    "time_range": {
      "start": "2026-01-19T00:00:00Z",
      "end": "2026-01-19T23:59:59Z"
    },
    "rate_limit": {
      "daily_remaining": 47
    },
    "request_id": "10615c94-d835-413e-ad3f-57c5a4c2276b",
    "scroll_id": "FGluY2x1ZGVfY29udGV4hYmMxMjN4eXpkZWY0NTZ1dnd..."
  }
}

Response Fields:

  • data.logs (array): Array of log objects
    • _index (string): OpenSearch index name
    • _id (string): Unique log identifier
    • _score (number): Relevance score
    • _source (object): Log content - fields vary by application and log type
  • data.count (integer): Total number of logs matching the query
  • meta.api_version (string): API version
  • meta.time_range (object): Query time range
  • meta.rate_limit.daily_remaining (integer): Remaining API calls for the day
  • meta.request_id (string): Unique request identifier
  • meta.scroll_id (string): Pagination token for retrieving next batch of results
POST     /v2/logs/batch

Description: Recommended for queries retrieving > 100,000 logs. Returns a token to access presigned URLs containing batches of logs.

Usage Flow:

  1. Call /v2/logs/batch → Get a token
  2. Call /v2/logs/batch/status with the token → Check status and get download URLs
  3. Poll periodically - each partition can be downloaded when it shows completed: true
  4. Download logs from the presigned URLs

Request Body (EC2/Kubernetes):

{
  "application": "atr",
  "app_type": "kubernetes",
  "start_time": "2026-01-19T00:00:00Z",
  "end_time": "2026-01-19T23:59:59Z",
  "domain": ["domain1.com", "domain2.com"],
  "fields": ["timestamp", "message", "level"]
}

Request Body (Serverless):

{
  "application": "eventops",
  "app_type": "serverless",
  "start_time": "2026-01-19T00:00:00Z",
  "end_time": "2026-01-19T23:59:59Z",
  "log_group": ["*"],
  "tenant": ["tenant1"],
  "stage": ["prod"],
  "fields": ["@timestamp", "logLevel", "function_name", "request.method"],
  "filters": [
    {"term": {"message.keyword": "KeyError occurred"}},
    {"term": {"function_memory_size": "1024"}}
  ]
}

Required Fields:

  • start_time (string): Start time in ISO 8601 format (e.g., "2026-01-19T00:00:00Z" or "2026-01-19T00:00:00.000Z")
  • end_time (string): End time in ISO 8601 format
  • application (string): Application name. Options: "atr", "klewer", "eventops", "quasar"
  • app_type (string): Application type. Options: "ec2", "kubernetes", "serverless"

Plus these depending on app_type:

  • For serverless:
    • log_group (array): List of log groups or ["*"] for all
    • tenant (array): List of tenants or ["*"] for all
    • stage (array): List of stages or ["*"] for all
  • For ec2/kubernetes:
    • domain (array): List of domain names or ["*"] for all

Optional Fields:

  • filters (array): List of OpenSearch filter objects to apply. See OpenSearch Query DSL for full syntax. Supported filter types:
    • term - Exact match on a field
    • terms - Match any of multiple values
    • range - Numeric or date range queries
    • exists - Check if a field exists
    • bool - Combine filters with nested logic (must, should, must_not)
    • match / match_phrase - Full-text search
  • fields (array): List of fields to include in response (if not provided, all fields are included)

Special Rules:

  • App Type Restrictions:
    • serverless → requires log_group, tenant, stage
    • ec2/kubernetes → requires domain
  • Wildcard Usage:
    • When using "*" in arrays, it must be the only element: ["*"]
    • Cannot mix wildcard with other values: ["*", "something"]

Response (200):

{
  "data": {
    "token": "a6EBWDj2yr5v1UUG"
  },
  "meta": {
    "api_version": "v2",
    "time_range": {
      "start": "2026-01-20T03:35:03.399316Z",
      "end": "2026-01-20T06:55:03.399316Z"
    },
    "rate_limit": {
      "daily_remaining": 49
    },
    "request_id": "dbfc4889-a1da-40d0-8dc9-3e08ef3e913c",
    "app_type": "kubernetes",
    "domain": ["*"]
  }
}

Response Fields:

  • data.token (string): Access token for retrieving presigned URLs via /v2/logs/batch/status
  • meta.api_version (string): API version
  • meta.time_range (object): Query time range
  • meta.rate_limit.daily_remaining (integer): Remaining API calls for the day
  • meta.request_id (string): Unique request identifier
  • meta.app_type (string): Application type from the request
  • meta.domain (array): Domain(s) from the request (present for ec2/kubernetes requests)
  • meta.log_group (array): Log group(s) from the request (present for serverless requests)
  • meta.tenant (array): Tenant(s) from the request (present for serverless requests)
  • meta.stage (array): Stage(s) from the request (present for serverless requests)
POST     /v2/logs/batch/status

Description: Use token from /v2/logs/batch response to retrieve presigned URLs for S3 buckets containing batches of logs.

Usage Flow:

  1. Call /v2/logs/batch → Get a token
  2. Call /v2/logs/batch/status with the token → Check status and get download URLs
  3. Poll periodically - each partition can be downloaded when it shows completed: true
  4. Download logs from the presigned URLs

Request Body:

{
  "token": "Paw21VHC3VxAs7F4"
}

Required Fields:

  • token (string): Token from the batch request

Request Validation:

  • Token is trimmed of whitespace
  • Empty or whitespace-only tokens are rejected

Response (200):

{
  "presigned_urls": [
    {
      "start_time": "2026-01-20T03:52:06.960046Z",
      "end_time": "2026-01-20T07:12:06.960046Z",
      "log_count": 1234,
      "presigned_url": "https://s3.amazonaws.com/...",
      "completed": true,
      "status": "completed"
    }
  ]
}

Response Fields:

  • presigned_urls (array): Contains one object per partition
    • start_time (string): Start time of this partition's time range
    • end_time (string): End time of this partition's time range
    • log_count (integer): Number of logs in this partition (0 if none)
    • presigned_url (string): S3 presigned URL to download the logs (or "null" if not ready)
    • completed (boolean): Indicates if this partition is ready for download
    • status (string): Status of the partition (e.g., "completed", "processing", "pending")
POST     /v2/logs/aggs

Description: Retrieve aggregated statistics and analytics from logs using OpenSearch aggregation queries. Supports terms aggregations, histograms, metrics, and nested aggregations.

Request Body (EC2/Kubernetes):

{
  "application": "atr",
  "app_type": "kubernetes",
  "start_time": "2026-01-19T00:00:00Z",
  "end_time": "2026-01-19T23:59:59Z",
  "domain": ["domain1.com", "domain2.com"],
  "aggs": {
    "log_levels": {
      "terms": {
        "field": "regex.extractions.logLevel",
        "size": 10
      }
    },
    "logs_over_time": {
      "date_histogram": {
        "field": "@timestamp",
        "fixed_interval": "1h"
      }
    }
  }
}

Request Body (Serverless):

{
  "application": "eventops",
  "app_type": "serverless",
  "start_time": "2026-01-19T00:00:00Z",
  "end_time": "2026-01-19T23:59:59Z",
  "log_group": ["*"],
  "tenant": ["tenant1"],
  "stage": ["prod"],
  "aggs": {
    "event_origins": {
      "terms": {
        "field": "event.origin",
        "size": 20
      }
    },
    "error_count": {
      "filter": {
        "term": {"logLevel": "ERROR"}
      }
    }
  }
}

Required Fields:

  • application (string): Name of the monitored application. Options: "atr", "klewer", "eventops", "quasar"
  • start_time (string): Start time in ISO 8601 format (e.g., "2026-01-19T00:00:00Z" or "2026-01-19T00:00:00.000Z")
  • end_time (string): End time in ISO 8601 format
  • app_type (string): Application type. Options: "ec2", "kubernetes", "serverless"
  • aggs (object): OpenSearch aggregation definition (must contain at least one aggregation)

Plus these depending on app_type:

  • For serverless:
    • log_group (array): List of log groups or ["*"] for all
    • tenant (array): List of tenants or ["*"] for all
    • stage (array): List of stages or ["*"] for all
  • For ec2/kubernetes:
    • domain (array): List of domain names or ["*"] for all

Aggregation Types:

The aggs field accepts any valid OpenSearch aggregation. Common types include:

  • Terms Aggregation - Group by field values:
"aggs": {"by_field": {"terms": {"field": "field_name","size": 10}}}
  • Date Histogram - Group by time intervals:
"aggs": {"over_time": {"date_histogram": {"field": "@timestamp","fixed_interval": "1h"}}}
  • Filter Aggregation - Count documents matching criteria:
"aggs": {"error_logs": {"filter": {"term": {"logLevel": "ERROR"}}}}
  • Nested Aggregations - Combine multiple aggregations:
"aggs": {"by_domain": {"terms": {"field": "atr.domain_name","size": 10},"aggs": {"by_level": {"terms": {"field": "regex.extractions.logLevel","size": 5}}}}}
  • Filter with Sub-aggregations - Analyze subset of data:
"aggs": {"error_analysis": {"filter": {"term": {"regex.extractions.logLevel": "ERROR"}},"aggs": {"hourly_errors": {"date_histogram": {"field": "@timestamp","fixed_interval": "1h"}}}}}

See OpenSearch Aggregations for full syntax.

Special Rules:

  • App Type Restrictions:
    • serverless → requires log_group, tenant, stage
    • ec2/kubernetes → requires domain
  • Wildcard Usage:
    • When using "*" in arrays, it must be the only element: ["*"]
    • Cannot mix wildcard with other values: ["*", "something"]
  • Time Range:
    • end_time must be after start_time
    • No maximum time range limit

Sample Response (200):

{
  "data": {
    "aggregations": {
      "log_levels": {
        "doc_count_error_upper_bound": 0,
        "sum_other_doc_count": 0,
        "buckets": [
          {"key": "WARN", "doc_count": 117315928},
          {"key": "INFO", "doc_count": 33176681},
          {"key": "ERROR", "doc_count": 107146}
        ]
      },
      "logs_over_time": {
        "buckets": [
          {"key_as_string": "2026-01-19T00:00:00.000Z", "key": 1737244800000, "doc_count": 45231},
          {"key_as_string": "2026-01-19T01:00:00.000Z", "key": 1737248400000, "doc_count": 52187}
        ]
      }
    },
    "total_documents": 269456123
  },
  "meta": {
    "api_version": "v2",
    "time_range": {
      "start": "2026-01-19T00:00:00Z",
      "end": "2026-01-19T23:59:59Z"
    },
    "rate_limit": {
      "daily_remaining": 999
    },
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "application": "atr",
    "app_type": "kubernetes",
    "domain": ["domain1.com", "domain2.com"]
  }
}

Response Fields:

  • data.aggregations (object): Aggregation results - structure varies based on your aggregation definition
    • For terms aggregations: Contains buckets array with key and doc_count
    • For date histograms: Contains buckets array with key_as_string, key, and doc_count
    • For filter aggregations: Contains doc_count number
    • For nested aggregations: Contains nested aggregation results
  • data.total_documents (integer): Total number of logs matching the query (before aggregation)
  • meta.api_version (string): API version
  • meta.time_range (object): Query time range
  • meta.rate_limit.daily_remaining (integer): Remaining API calls for the day
  • meta.request_id (string): Unique request identifier
  • meta.application (string): Application name from request
  • meta.app_type (string): Application type from request
  • meta.domain (array): Domain filter (for non-serverless)
  • meta.log_group (array): Log group filter (for serverless)
  • meta.tenant (array): Tenant filter (for serverless)
  • meta.stage (array): Stage filter (for serverless)
V3
POST     /v3/logs/mappings

Description: Retrieve all available fields and their data types from a logs index. Useful for discovering which fields can be used in filters, fields, and aggs parameters. The index is resolved dynamically based on the application and app_type provided.

Request Body:

{
  "application": "atr",
  "app_type": "ec2",
  "includes_eu": false
}

Required Fields:

  • application (string): Application name. Options: "atr", "klewer", "eventops", "quasar", "agentmanager"
  • app_type (string): Application type. Options: "ec2", "kubernetes", "serverless"

Optional Fields:

  • includes_eu (boolean): Include EU cross-cluster indices (default: true). Set to false to query only the local region

Valid Combinations:

applicationapp_type
atrec2, kubernetes
klewerec2, kubernetes
quasarec2, kubernetes
eventopsserverless
agentmanagerserverless

Special Rules:

  • App Type Restrictions:
    • eventops and agentmanager only support serverless
    • atr, klewer, and quasar do not support serverless
  • Extra Fields:
    • Unknown fields in the request body are rejected (HTTP 400)

Sample Response (200):

{
  "data": {
    "fields": [
      {"name": "@timestamp", "type": "date"},
      {"name": "atr.domain_name", "type": "keyword"},
      {"name": "message", "type": "text"},
      {"name": "message.keyword", "type": "keyword"},
      {"name": "regex.extractions.logLevel", "type": "keyword"}
    ],
    "field_count": 85
  },
  "meta": {
    "trace_id": "1-69d8732e-152bf5df11c3f9fe417af0bf",
    "rate_limit": {
      "daily_remaining": 998
    }
  }
}

Response Fields:

  • data.fields (array): Array of field objects, sorted alphabetically by name
    • name (string): Full field path (e.g., "regex.extractions.logLevel")
    • type (string): OpenSearch field type (e.g., "keyword", "text", "date", "float", "boolean", "long", "integer", "alias")
  • data.field_count (integer): Total number of fields
  • meta.trace_id (string): X-Ray trace ID for debugging
  • meta.rate_limit.daily_remaining (integer): Remaining API calls for the day

Notes:

  • Fields with multi-field mappings appear as separate entries (e.g., message as text and message.keyword as keyword)
  • Use keyword type fields for exact match filters (term, terms) and aggregations
  • Use text type fields for full-text search (match, match_phrase)
  • Different application + app_type combinations query different indices with different field schemas

Workloads​

V2
POST     /v2/workloads/scroll

Description: Recommended for queries retrieving < 100,000 workloads. Retrieve workloads using cursor-based pagination with the returned scroll_id.

Request Body (EC2):

{
  "application": "atr",
  "app_type": "ec2",
  "start_time": "2026-01-19T00:00:00Z",
  "end_time": "2026-01-19T23:59:59Z",
  "domain": ["domain1.com", "domain2.com"],
  "size": 100,
  "fields": ["timestamp", "workload_id", "status"],
  "filters": [
    {
      "bool": {
        "must": [
          {"term": {"ticket.type": "SR_TASK"}},
          {"term": {"workload.trigger": "TICKET"}}
        ],
        "must_not": [
          {"term": {"workload.state": "FAILED"}}
        ]
      }
    }
  ]
}

Request Body (Kubernetes):

{
  "application": "atr",
  "app_type": "kubernetes",
  "start_time": "2026-01-19T00:00:00Z",
  "end_time": "2026-01-19T23:59:59Z",
  "domain": ["*"],
  "size": 50,
  "filters": [
    {"terms": {"workflow.name": ["Incident_Response_Workflow", "Scheduled_Maintenance_Workflow"]}}
  ]
}

Request Body (Pagination):

{
  "scroll_id": "DnF1ZXJ5VGhlbkZldGNoAwAAAAAAAAABFmtQN..."
}

Required Fields (Initial Request):

  • application (string): Application name. Only "atr" is supported
  • start_time (string): Start time in ISO 8601 format (e.g., "2026-01-19T00:00:00Z" or "2026-01-19T00:00:00.000Z")
  • end_time (string): End time in ISO 8601 format
  • app_type (string): Application type. Options: "ec2", "kubernetes"
  • domain (array): List of domain names or ["*"] for all (cannot be empty)

Optional Fields:

  • size (integer): Number of results to return (must be > 0)
  • filters (array): List of OpenSearch filter objects to apply. See OpenSearch Query DSL for full syntax. Supported filter types:
    • term - Exact match on a field
    • terms - Match any of multiple values
    • range - Numeric or date range queries
    • exists - Check if a field exists
    • bool - Combine filters with nested logic (must, should, must_not)
    • match / match_phrase - Full-text search
  • fields (array): List of fields to include in response (if not provided, all fields are included)
  • scroll_id (string): For pagination (when provided, only this field is required and all others become optional)

Special Rules:

  • Application Restrictions:
    • Only "atr" is supported for workloads
    • No serverless support (only "ec2" and "kubernetes")
  • Domain Field:
    • Must be a list of strings
    • Cannot be empty
    • When using "*" in arrays, it must be the only element: ["*"]
    • Cannot mix wildcard with other values: ["*", "domain1"]
  • Scroll ID Requests:
    • If scroll_id is provided, all other fields become optional
    • Used for pagination to get next batch of results

Sample Response (200):

{
  "data": {
    "workloads": [
      {
        "_index": "workloads-atr-2026-01",
        "_id": "wl-abc123",
        "_score": 1.0,
        "_source": {
          "...": "Workload content varies by application"
        }
      }
    ],
    "count": 50
  },
  "meta": {
    "api_version": "v2",
    "time_range": {
      "start": "2026-01-20T03:52:06.960046Z",
      "end": "2026-01-20T07:12:06.960046Z"
    },
    "rate_limit": {
      "daily_remaining": 48
    },
    "request_id": "3a5f1229-ccef-4fcb-be27-98fd88e950c7",
    "app_type": "kubernetes",
    "domain": ["domain1.com", "domain2.com"],
    "scroll_id": "DnF1ZXJ5VGhlbkZldGNo...",
    "workloads_available": 150
  }
}

Response Fields:

  • data.workloads (array): Array of workload objects
    • _index (string): OpenSearch index name
    • _id (string): Unique workload identifier
    • _score (number): Relevance score
    • _source (object): Workload content - fields vary by application and workload type
  • data.count (integer): Number of workloads returned in this response
  • meta.api_version (string): API version
  • meta.time_range (object): Query time range
  • meta.rate_limit.daily_remaining (integer): Remaining API calls for the day
  • meta.request_id (string): Unique request identifier
  • meta.app_type (string): Application type from request
  • meta.domain (array): List of domains queried
  • meta.scroll_id (string): Pagination token (present when more results available)
  • meta.workloads_available (integer): Total workloads available (optional)
POST     /v2/workloads/batch

Description: Recommended for queries retrieving > 100,000 workloads. Returns a token to access presigned URLs containing batches of workloads.

Usage Flow:

  1. Call /v2/workloads/batch → Get a token
  2. Call /v2/workloads/batch/status with the token → Check status and get download URLs
  3. Poll periodically - each partition can be downloaded when it shows completed: true
  4. Download workloads from the presigned URLs

Request Body (Minimal):

{
  "application": "atr",
  "app_type": "ec2",
  "start_time": "2026-01-19T00:00:00Z",
  "end_time": "2026-01-19T23:59:59Z",
  "domain": ["domain1.com", "domain2.com"]
}

Request Body (With Filters):

{
  "application": "atr",
  "app_type": "kubernetes",
  "start_time": "2026-01-19T00:00:00Z",
  "end_time": "2026-01-19T23:59:59Z",
  "domain": ["*"],
  "filters": [
    {
      "bool": {
        "must": [
          {"term": {"ticket.type": "SR_TASK"}},
          {"term": {"workload.trigger": "TICKET"}}
        ],
        "must_not": [
          {"term": {"workload.state": "FAILED"}}
        ]
      }
    }
  ]
}

Request Body (With Field Selection):

{
  "application": "atr",
  "app_type": "kubernetes",
  "start_time": "2026-01-19T00:00:00Z",
  "end_time": "2026-01-19T23:59:59Z",
  "domain": ["domain1.com"],
  "fields": ["timestamp", "workload_id", "status", "workflow.name"]
}

Required Fields:

  • application (string): Application name. Only "atr" is supported
  • start_time (string): Start time in ISO 8601 format (e.g., "2026-01-19T00:00:00Z" or "2026-01-19T00:00:00.000Z")
  • end_time (string): End time in ISO 8601 format
  • app_type (string): Application type. Options: "ec2", "kubernetes"
  • domain (array): List of domain names or ["*"] for all (cannot be empty)

Optional Fields:

  • filters (array): List of OpenSearch filter objects to apply. See OpenSearch Query DSL for full syntax. Supported filter types:
    • term - Exact match on a field
    • terms - Match any of multiple values
    • range - Numeric or date range queries
    • exists - Check if a field exists
    • bool - Combine filters with nested logic (must, should, must_not)
    • match / match_phrase - Full-text search
  • fields (array): List of fields to include in response (if not provided, all fields are included)

Special Rules:

  • Application Restrictions:
    • Only "atr" is supported for workloads
    • No serverless support (only "ec2" and "kubernetes")
  • Domain Field:
    • Must be a list of strings
    • Cannot be empty
    • When using "*" in arrays, it must be the only element: ["*"]
    • Cannot mix wildcard with other values: ["*", "domain1"]

Response (200):

{
  "data": {
    "token": "Paw21VHC3VxAs7F4"
  },
  "meta": {
    "api_version": "v2",
    "time_range": {
      "start": "2026-01-20T03:52:06.960046Z",
      "end": "2026-01-20T07:12:06.960046Z"
    },
    "rate_limit": {
      "daily_remaining": 48
    },
    "request_id": "3a5f1229-ccef-4fcb-be27-98fd88e950c7",
    "app_type": "kubernetes",
    "domain": ["domain1.com", "domain2.com"]
  }
}

Response Fields:

  • data.token (string): Access token for retrieving presigned URLs via /v2/workloads/batch/status
  • meta.api_version (string): API version
  • meta.time_range (object): Query time range
  • meta.rate_limit.daily_remaining (integer): Remaining API calls for the day
  • meta.request_id (string): Unique request identifier
  • meta.app_type (string): Application type from the request
  • meta.domain (array): Domain(s) from the request
POST     /v2/workloads/batch/status

Description: Use token from /v2/workloads/batch response to retrieve presigned URLs for S3 buckets containing batches of workloads.

Usage Flow:

  1. Call /v2/workloads/batch → Get a token
  2. Call /v2/workloads/batch/status with the token → Check status and get download URLs
  3. Poll periodically - each partition can be downloaded when it shows completed: true
  4. Download workloads from the presigned URLs

Request Body:

{
  "token": "Paw21VHC3VxAs7F4"
}

Required Fields:

  • token (string): Token from the batch request (must be non-empty)

Request Validation:

  • Token is trimmed of whitespace
  • Empty or whitespace-only tokens are rejected

Response (200):

{
  "presigned_urls": [
    {
      "start_time": "2026-01-21T08:00:00Z",
      "end_time": "2026-01-21T14:00:00Z",
      "workload_count": 1523,
      "presigned_url": "https://s3.amazonaws.com/...",
      "completed": true,
      "status": "completed"
    },
    {
      "start_time": "2026-01-21T14:00:00Z",
      "end_time": "2026-01-21T20:00:00Z",
      "workload_count": 892,
      "presigned_url": "null",
      "completed": false,
      "status": "processing"
    }
  ]
}

Response Fields:

  • presigned_urls (array): Contains one object per partition
    • start_time (string): Start time of this partition's time range
    • end_time (string): End time of this partition's time range
    • workload_count (integer): Number of workloads in this partition
    • presigned_url (string): S3 presigned URL to download the workloads (or "null" if not ready)
    • completed (boolean): Indicates if this partition is ready for download
    • status (string): Status of the partition (e.g., "completed", "processing", "failed")
POST     /v2/workloads/aggs

Description: Retrieve aggregated statistics and analytics from workloads using OpenSearch aggregation queries. Supports terms aggregations, histograms, metrics, and nested aggregations for analyzing workflow execution patterns.

Request Body:

{
  "application": "atr",
  "app_type": "kubernetes",
  "start_time": "2026-01-19T00:00:00Z",
  "end_time": "2026-01-19T23:59:59Z",
  "domain": ["domain1.com", "domain2.com"],
  "aggs": {
    "by_workflow": {
      "terms": {
        "field": "workflow.name",
        "size": 20
      }
    },
    "by_domain": {
      "terms": {
        "field": "atr.domain_name",
        "size": 10
      }
    },
    "over_time": {
      "date_histogram": {
        "field": "@timestamp",
        "fixed_interval": "1h"
      }
    }
  }
}

Request Body (with filter):

{
  "application": "atr",
  "app_type": "kubernetes",
  "start_time": "2025-01-01T00:00:00Z",
  "end_time": "2026-01-28T23:59:59Z",
  "domain": ["*"],
  "aggs": {
    "incident_workflow_count": {
      "filter": {
        "term": {"workflow.name": "Incident_Response_Workflow"}
      }
    },
    "workflow_distribution": {
      "terms": {
        "field": "workflow.name",
        "size": 50
      }
    }
  }
}

Required Fields:

  • application (string): Name of the monitored application. Options: "atr"
  • start_time (string): Start time in ISO 8601 format (e.g., "2026-01-19T00:00:00Z" or "2026-01-19T00:00:00.000Z")
  • end_time (string): End time in ISO 8601 format
  • app_type (string): Application type. Options: "ec2", "kubernetes"
  • domain (array): List of domain names or ["*"] for all domains
  • aggs (object): OpenSearch aggregation definition (must contain at least one aggregation)

Aggregation Types:

The aggs field accepts any valid OpenSearch aggregation. Common types include:

  • Terms Aggregation - Group by field values:
"aggs": {"by_workflow": {"terms": {"field": "workflow.name","size": 20}}}
  • Date Histogram - Group by time intervals:
"aggs": {"over_time": {"date_histogram": {"field": "@timestamp","fixed_interval": "1d"}}}
  • Filter Aggregation - Count documents matching criteria:
"aggs": {"specific_workflow": {"filter": {"term": {"workflow.name": "Data_Processing_Workflow"}}}}
  • Nested Aggregations - Combine multiple aggregations:
"aggs": {"by_domain": {"terms": {"field": "atr.domain_name","size": 10},"aggs": {"by_workflow": {"terms": {"field": "workflow.name","size": 5}}}}}
  • Filter with Sub-aggregations - Analyze subset of data:
"aggs": {"incident_analysis": {"filter": {"term": {"workflow.name": "Incident_Response_Workflow"}},"aggs": {"daily_counts": {"date_histogram": {"field": "@timestamp","fixed_interval": "1d"}}}}}

See OpenSearch Aggregations for full syntax.

Special Rules:

  • Wildcard Usage:
    • When using "*" in domain array, it must be the only element: ["*"]
    • Cannot mix wildcard with other values: ["*", "something"]
  • Time Range:
    • end_time must be after start_time
    • No maximum time range limit

Sample Response (200):

{
  "data": {
    "aggregations": {
      "by_workflow": {
        "doc_count_error_upper_bound": 0,
        "sum_other_doc_count": 125000,
        "buckets": [
          {"key": "Incident_Response_Workflow", "doc_count": 3126831},
          {"key": "Scheduled_Maintenance_Workflow", "doc_count": 1048182},
          {"key": "Data_Enrichment_Workflow", "doc_count": 745352}
        ]
      },
      "by_domain": {
        "doc_count_error_upper_bound": 0,
        "sum_other_doc_count": 0,
        "buckets": [
          {"key": "domain1.com", "doc_count": 2500000},
          {"key": "domain2.com", "doc_count": 1800000}
        ]
      },
      "over_time": {
        "buckets": [
          {"key_as_string": "2026-01-19T00:00:00.000Z", "key": 1737244800000, "doc_count": 125000},
          {"key_as_string": "2026-01-19T01:00:00.000Z", "key": 1737248400000, "doc_count": 132000}
        ]
      }
    },
    "total_documents": 5234567
  },
  "meta": {
    "api_version": "v2",
    "time_range": {
      "start": "2026-01-19T00:00:00Z",
      "end": "2026-01-19T23:59:59Z"
    },
    "rate_limit": {
      "daily_remaining": 999
    },
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "app_type": "kubernetes",
    "domain": ["domain1.com", "domain2.com"]
  }
}

Response Fields:

  • data.aggregations (object): Aggregation results - structure varies based on your aggregation definition
    • For terms aggregations: Contains buckets array with key and doc_count
    • For date histograms: Contains buckets array with key_as_string, key, and doc_count
    • For filter aggregations: Contains doc_count number
    • For nested aggregations: Contains nested aggregation results
  • data.total_documents (integer): Total number of workloads matching the query (before aggregation)
  • meta.api_version (string): API version
  • meta.time_range (object): Query time range
  • meta.rate_limit.daily_remaining (integer): Remaining API calls for the day
  • meta.request_id (string): Unique request identifier
  • meta.app_type (string): Application type from request
  • meta.domain (array): Domain filter from request

Common Fields for Workloads:

  • workflow.name - Workflow identifier
  • atr.domain_name - Domain name
  • atr.infra_type - Infrastructure type (kubernetes, ec2)
  • @timestamp - Timestamp of workload execution
  • workload.state - Workload state (e.g., "DONE", "FAILED", etc.)

You can also explore available fields using OpenSearch Dashboards Discover.

V3
POST     /v3/workloads/mappings

Description: Retrieve all available fields and their data types from the workloads index. Useful for discovering which fields can be used in filters, fields, and aggs parameters.

Request Body:

{
  "includes_eu": false
}

Optional Fields:

  • includes_eu (boolean): Include EU cross-cluster indices (default: true). Set to false to query only the local region

Special Rules:

  • Extra Fields:
    • Unknown fields in the request body are rejected (HTTP 400)
  • An empty body or {} is valid and defaults to includes_eu: true

Sample Response (200):

{
  "data": {
    "fields": [
      {"name": "@timestamp", "type": "date"},
      {"name": "atr.domain_name", "type": "keyword"},
      {"name": "atr.infra_type", "type": "keyword"},
      {"name": "workflow.name", "type": "keyword"},
      {"name": "workload.state", "type": "keyword"},
      {"name": "workload.execution_time.elapsed", "type": "float"}
    ],
    "field_count": 120
  },
  "meta": {
    "trace_id": "1-69d8732e-152bf5df11c3f9fe417af0bf",
    "rate_limit": {
      "daily_remaining": 998
    }
  }
}

Response Fields:

  • data.fields (array): Array of field objects, sorted alphabetically by name
    • name (string): Full field path (e.g., "workload.execution_time.elapsed")
    • type (string): OpenSearch field type (e.g., "keyword", "text", "date", "float", "boolean", "long", "integer", "alias")
  • data.field_count (integer): Total number of fields
  • meta.trace_id (string): X-Ray trace ID for debugging
  • meta.rate_limit.daily_remaining (integer): Remaining API calls for the day

Notes:

  • Fields with multi-field mappings appear as separate entries (e.g., workflow.name as keyword and workflow.name.text as text)
  • Use keyword type fields for exact match filters (term, terms) and aggregations
  • Use text type fields for full-text search (match, match_phrase)
  • Use date type fields for time-based range queries and date histogram aggregations

Jobs​

V3
POST     /v3/jobs/query

Description: Query job execution documents with cursor-based pagination using Point in Time (PIT) and search_after.

Request Body (Initial Request):

{
  "application": "atr",
  "app_type": ["ec2", "kubernetes"],
  "domain": ["your-domain.example.com"],
  "start_time": "2026-01-01T00:00:00Z",
  "end_time": "2026-03-20T23:59:59Z",
  "size": 1000,
  "fields": ["job.name", "job.state", "workflow.name", "atr.domain_name"],
  "includes_eu": false,
  "filters": [
    {"term": {"job.state": "DONE"}},
    {"term": {"atr.infra_type": "kubernetes"}}
  ]
}

Request Body (Pagination):

{
  "pit_id": "previous_pit_id_here",
  "search_after": [1774038927000],
  "size": 1000,
  "fields": ["job.name", "job.state"]
}

Required Fields (Initial Request):

  • application (string): Application name. Only "atr" is supported
  • start_time (string): Start time in ISO 8601 format (e.g., "2026-01-19T00:00:00Z" or "2026-01-19T00:00:00.000Z")
  • end_time (string): End time in ISO 8601 format
  • app_type (array): Application types. Options: "ec2", "kubernetes" (e.g., ["ec2"] or ["ec2", "kubernetes"])
  • domain (array): List of domain names or ["*"] for all (cannot be empty)

Optional Fields:

  • size (integer): Number of results per page (default: 100, max: 10000, must be greater than 0)
  • filters (array): List of OpenSearch filter objects to apply. See OpenSearch Query DSL for full syntax. Supported filter types:
    • term - Exact match on a field
    • terms - Match any of multiple values
    • range - Numeric or date range queries
    • exists - Check if a field exists
    • bool - Combine filters with nested logic (must, should, must_not)
    • match / match_phrase - Full-text search
  • fields (array): List of fields to include in response (if not provided, all fields are returned)
  • includes_eu (boolean): Include EU region search (default: true). Set to false to query only the local region for faster response times
  • pit_id (string): Point in Time ID for pagination (must be provided together with search_after)
  • search_after (array): Sort values from the last hit of the previous page (must be provided together with pit_id)

Special Rules:

  • Pagination:
    • pit_id and search_after must both be provided together
    • When paginating, application, start_time, end_time, app_type, and domain are not required
    • The pit_id and search_after values are returned in the response meta.pagination object
    • When meta.pagination.pit_id is null, the last page has been reached
  • Domain Field:
    • Must be a list of strings
    • Cannot be empty
    • When using "*", it must be the only element: ["*"]
    • Cannot mix wildcard with other values: ["*", "domain1"]
  • App Type Field:
    • Must be a list (e.g., ["ec2"] not "ec2")
    • Only "ec2" and "kubernetes" are valid values
  • Cross Region Search:
    • By default (includes_eu: true), the query searches across all regional databases, including EU
    • Set includes_eu: false to query only the local region for reduced latency
  • Response Size:
    • If the response exceeds the safe payload limit, a 413 error is returned
    • Use the fields parameter, reduce size to limit response size, or use a batch endpoint instead
  • Extra Fields:
    • Unknown fields in the request body are rejected (HTTP 400)

Sample Response (200):

{
  "data": {
    "hits": [
      {
        "_index": "jobs-atr-2026-v2",
        "_id": "69d83f28833f6c77f741609e",
        "_score": null,
        "_source": {
          "job": {
            "name": "<job_name>",
            "state": "DONE"
          },
          "workflow": {
            "name": "<workflow_name>"
          },
          "atr": {
            "domain_name": "<domain_name>",
            "infra_type": "kubernetes"
          }
        },
        "sort": [1775779626000]
      }
    ],
    "total": 319455,
    "count": 1000
  },
  "meta": {
    "trace_id": "1-69d8732e-152bf5df11c3f9fe417af0bf",
    "rate_limit": {
      "daily_remaining": 9950
    },
    "pagination": {
      "pit_id": "FGluY2x1ZGVfY29udGV4...",
      "search_after": [1775779626000]
    }
  }
}

Response Fields:

  • data.hits (array): Array of job documents
    • _index (string): OpenSearch index name
    • _id (string): Unique job identifier
    • _source (object): Job content (fields vary based on fields parameter; all fields returned if not specified)
    • sort (array): Sort values used for pagination
  • data.total (integer): Total number of jobs matching the query
  • data.count (integer): Number of jobs returned in this page
  • meta.trace_id (string): X-Ray trace ID for debugging
  • meta.rate_limit.daily_remaining (integer): Remaining API calls for the day
  • meta.pagination.pit_id (string or null): Point in Time ID for next page (null when last page reached)
  • meta.pagination.search_after (array or null): Sort values for next page (null when last page reached)

Last Page: When the last page is reached, pit_id and search_after will both be null. The Point in Time is automatically cleaned up — no additional action is needed.

Common Job Fields:

  • job.name - Job name
  • job.id - Unique job identifier
  • job.state - Job state (e.g., "DONE", "FAILED")
  • job.execution_time.start - Job start timestamp
  • job.execution_time.end - Job end timestamp
  • job.execution_time.elapsed - Execution duration in seconds
  • workflow.name - Workflow name
  • workflow.id - Workflow identifier
  • workload.id - Parent workload identifier
  • workload.state - Workload state
  • atr.domain_name - Domain name
  • atr.infra_type - Infrastructure type ("ec2", "kubernetes")
  • atr.client - Client name
  • atr.environment - Environment
  • ticket.number - Associated ticket number
  • ticket.type - Associated ticket type
  • @timestamp - Document timestamp
POST     /v3/jobs/aggs

Description: Retrieve aggregated statistics and analytics from jobs using OpenSearch aggregation queries. Supports terms aggregations, histograms, metrics, and nested aggregations for analyzing job execution patterns.

Request Body:

{
  "application": "atr",
  "app_type": ["ec2", "kubernetes"],
  "domain": ["your-domain.example.com"],
  "start_time": "2026-01-01T00:00:00Z",
  "end_time": "2026-03-20T23:59:59Z",
  "includes_eu": false,
  "aggs": {
    "jobs_by_state": {
      "terms": {
        "field": "job.state",
        "size": 20
      }
    },
    "jobs_over_time": {
      "date_histogram": {
        "field": "@timestamp",
        "fixed_interval": "1d"
      }
    },
    "top_job_names": {
      "terms": {
        "field": "job.name",
        "size": 10
      }
    }
  }
}

Request Body (With Filters):

{
  "application": "atr",
  "app_type": ["kubernetes"],
  "domain": ["*"],
  "start_time": "2026-01-01T00:00:00Z",
  "end_time": "2026-03-27T23:59:59Z",
  "includes_eu": true,
  "filters": [
    {"term": {"job.state": "FAILED"}},
    {"range": {"job.execution_time.elapsed": {"gte": 60}}}
  ],
  "aggs": {
    "failed_by_domain": {
      "terms": {
        "field": "atr.domain_name",
        "size": 20
      }
    },
    "failed_by_workflow": {
      "terms": {
        "field": "workflow.name",
        "size": 10
      },
      "aggs": {
        "avg_duration": {
          "avg": {
            "field": "job.execution_time.elapsed"
          }
        }
      }
    }
  }
}

Required Fields:

  • application (string): Application name. Only "atr" is supported
  • start_time (string): Start time in ISO 8601 format (e.g., "2026-01-19T00:00:00Z" or "2026-01-19T00:00:00.000Z")
  • end_time (string): End time in ISO 8601 format
  • app_type (array): Application types. Options: "ec2", "kubernetes" (e.g., ["ec2"] or ["ec2", "kubernetes"])
  • domain (array): List of domain names or ["*"] for all (cannot be empty)
  • aggs (object): OpenSearch aggregation definition (must contain at least one aggregation)

Optional Fields:

  • filters (array): List of OpenSearch filter objects to apply. See OpenSearch Query DSL for full syntax. Supported filter types:
    • term - Exact match on a field
    • terms - Match any of multiple values
    • range - Numeric or date range queries
    • exists - Check if a field exists
    • bool - Combine filters with nested logic (must, should, must_not)
    • match / match_phrase - Full-text search
  • includes_eu (boolean): Include EU region search (default: true). Set to false to query only the local region for faster response times

Aggregation Types:

The aggs field accepts any valid OpenSearch aggregation. Common types include:

  • Terms Aggregation - Group by field values:
"aggs": {"by_state": {"terms": {"field": "job.state","size": 20}}}
  • Date Histogram - Group by time intervals:
"aggs": {"over_time": {"date_histogram": {"field": "@timestamp","fixed_interval": "1d"}}}
  • Filter Aggregation - Count documents matching criteria:
"aggs": {"failed_jobs": {"filter": {"term": {"job.state": "FAILED"}}}}
  • Nested Aggregations - Combine multiple aggregations:
"aggs": {"by_domain": {"terms": {"field": "atr.domain_name","size": 10},"aggs": {"by_job": {"terms": {"field": "job.name","size": 5}}}}}
  • Filter with Sub-aggregations - Analyze subset of data:
"aggs": {"failed_analysis": {"filter": {"term": {"job.state": "FAILED"}},"aggs": {"daily_failures": {"date_histogram": {"field": "@timestamp","fixed_interval": "1d"}}}}}

See OpenSearch Aggregations for full syntax.

Special Rules:

  • App Type Field:
    • Must be a list (e.g., ["ec2"] not "ec2")
    • Only "ec2" and "kubernetes" are valid values
  • Domain Field:
    • Must be a list of strings
    • Cannot be empty
    • When using "*", it must be the only element: ["*"]
    • Cannot mix wildcard with other values: ["*", "domain1"]
  • Cross Region Search:
    • By default (includes_eu: true), the query searches across all regional databases, including EU
    • Set includes_eu: false to query only the local region for reduced latency
  • Time Range:
    • end_time must be after start_time
    • No maximum time range limit
  • Extra Fields:
    • Unknown fields in the request body are rejected (HTTP 400)

Sample Response (200):

{
  "data": {
    "aggregations": {
      "jobs_by_state": {
        "doc_count_error_upper_bound": 0,
        "sum_other_doc_count": 0,
        "buckets": [
          {"key": "DONE", "doc_count": 285231},
          {"key": "FAILED", "doc_count": 32187},
          {"key": "REJECTED", "doc_count": 1456}
        ]
      },
      "jobs_over_time": {
        "buckets": [
          {"key_as_string": "2026-01-01T00:00:00.000Z", "key": 1735689600000, "doc_count": 4523},
          {"key_as_string": "2026-01-02T00:00:00.000Z", "key": 1735776000000, "doc_count": 4687}
        ]
      },
      "top_job_names": {
        "doc_count_error_upper_bound": 0,
        "sum_other_doc_count": 125000,
        "buckets": [
          {"key": "<job_name_1>", "doc_count": 45231},
          {"key": "<job_name_2>", "doc_count": 32187},
          {"key": "<job_name_3>", "doc_count": 18456}
        ]
      }
    },
    "total": 319455
  },
  "meta": {
    "trace_id": "1-69d8732e-152bf5df11c3f9fe417af0bf",
    "rate_limit": {
      "daily_remaining": 9950
    },
    "pagination": {
      "pit_id": null,
      "search_after": null
    }
  }
}

Response Fields:

  • data.aggregations (object): Aggregation results - structure varies based on your aggregation definition
    • For terms aggregations: Contains buckets array with key and doc_count
    • For date histograms: Contains buckets array with key_as_string, key, and doc_count
    • For filter aggregations: Contains doc_count number
    • For nested aggregations: Contains nested aggregation results
  • data.total (integer): Total number of jobs matching the query (before aggregation)
  • meta.trace_id (string): X-Ray trace ID for debugging
  • meta.rate_limit.daily_remaining (integer): Remaining API calls for the day
  • meta.pagination.pit_id (null): Always null for aggregation queries (no pagination)
  • meta.pagination.search_after (null): Always null for aggregation queries (no pagination)

Common Job Fields for Aggregations:

  • job.name - Job name
  • job.state - Job state (e.g., "DONE", "FAILED", "REJECTED")
  • job.execution_time.elapsed - Execution duration in seconds
  • workflow.name - Workflow name
  • workload.state - Workload state
  • atr.domain_name - Domain name
  • atr.infra_type - Infrastructure type ("ec2", "kubernetes")
  • atr.client - Client name
  • atr.environment - Environment
  • @timestamp - Document timestamp

You can also explore available fields using the /v3/jobs/mappings endpoint or OpenSearch Dashboards Discover.

POST     /v3/jobs/mappings

Description: Retrieve all available fields and their data types from the jobs index. Useful for discovering which fields can be used in filters, fields, and aggs parameters.

Request Body:

{
  "includes_eu": false
}

Optional Fields:

  • includes_eu (boolean): Include EU cross-cluster indices (default: true). Set to false to query only the local region

Special Rules:

  • Extra Fields:
    • Unknown fields in the request body are rejected (HTTP 400)
  • An empty body or {} is valid and defaults to includes_eu: true

Sample Response (200):

{
  "data": {
    "fields": [
      {"name": "@timestamp", "type": "alias"},
      {"name": "atr.client", "type": "keyword"},
      {"name": "atr.domain_name", "type": "keyword"},
      {"name": "atr.infra_type", "type": "keyword"},
      {"name": "job.execution_time.elapsed", "type": "float"},
      {"name": "job.execution_time.end", "type": "date"},
      {"name": "job.execution_time.start", "type": "date"},
      {"name": "job.name", "type": "keyword"},
      {"name": "job.name.text", "type": "text"},
      {"name": "job.state", "type": "keyword"},
      {"name": "workflow.name", "type": "keyword"},
      {"name": "workload.state", "type": "keyword"}
    ],
    "field_count": 149
  },
  "meta": {
    "trace_id": "1-69d8732e-152bf5df11c3f9fe417af0bf",
    "rate_limit": {
      "daily_remaining": 998
    }
  }
}

Response Fields:

  • data.fields (array): Array of field objects, sorted alphabetically by name
    • name (string): Full field path (e.g., "job.execution_time.elapsed")
    • type (string): OpenSearch field type (e.g., "keyword", "text", "date", "float", "boolean", "long", "integer", "alias")
  • data.field_count (integer): Total number of fields
  • meta.trace_id (string): X-Ray trace ID for debugging
  • meta.rate_limit.daily_remaining (integer): Remaining API calls for the day

Notes:

  • Fields with multi-field mappings appear as separate entries (e.g., job.name as keyword and job.name.text as text)
  • Use keyword type fields for exact match filters (term, terms) and aggregations
  • Use text type fields for full-text search (match, match_phrase)
  • Use date type fields for time-based range queries and date histogram aggregations

Tickets​

V3
POST     /v3/tickets/query

Description: Recommended for retrieving < 200,000 tickets. Query ticket documents with cursor-based pagination using Point in Time (PIT) and search_after.

Request Body (Initial Request):

{
  "application": "atr",
  "app_type": ["ec2", "kubernetes"],
  "domain": ["your-domain.example.com"],
  "start_time": "2026-01-01T00:00:00Z",
  "end_time": "2026-03-20T23:59:59Z",
  "size": 1000,
  "fields": ["ticket.description", "ticket.number", "ticket.state"],
  "includes_eu": false,
  "filters": [
    {"term": {"ticket.resolved": true}},
    {"term": {"ticket.type": "SR_ITEM"}}
  ]
}

Request Body (Pagination):

{
  "pit_id": "previous_pit_id_here",
  "search_after": [1774038927000],
  "size": 1000,
  "fields": ["ticket.description"]
}

Required Fields (Initial Request):

  • application (string): Application name. Only "atr" is supported
  • start_time (string): Start time in ISO 8601 format (e.g., "2026-01-19T00:00:00Z" or "2026-01-19T00:00:00.000Z")
  • end_time (string): End time in ISO 8601 format
  • app_type (array): Application types. Options: "ec2", "kubernetes" (e.g., ["ec2"] or ["ec2", "kubernetes"])
  • domain (array): List of domain names or ["*"] for all (cannot be empty)

Optional Fields:

  • size (integer): Number of results per page (default: 100, max: 10000, must be greater than 0)
  • filters (array): List of OpenSearch filter objects to apply. See OpenSearch Query DSL for full syntax. Supported filter types:
    • term - Exact match on a field
    • terms - Match any of multiple values
    • range - Numeric or date range queries
    • exists - Check if a field exists
    • bool - Combine filters with nested logic (must, should, must_not)
    • match / match_phrase - Full-text search
  • fields (array): List of fields to include in response (if not provided, all fields are returned)
  • includes_eu (boolean): Include EU region search (default: true). Set to false to query only the local region for faster response times
  • pit_id (string): Point in Time ID for pagination (must be provided together with search_after)
  • search_after (array): Sort values from the last hit of the previous page (must be provided together with pit_id)

Special Rules:

  • Pagination:
    • pit_id and search_after must both be provided together
    • When paginating, application, start_time, end_time, app_type, and domain are not required
    • The pit_id and search_after values are returned in the response meta.pagination object
    • When meta.pagination.pit_id is null, the last page has been reached
  • Domain Field:
    • Must be a list of strings
    • Cannot be empty
    • When using "*", it must be the only element: ["*"]
    • Cannot mix wildcard with other values: ["*", "domain1"]
  • App Type Field:
    • Must be a list (e.g., ["ec2"] not "ec2")
    • Only "ec2" and "kubernetes" are valid values
  • Cross Region Search:
    • By default (includes_eu: true), the query searches across all regional databases, including EU
    • Set includes_eu: false to query only the local region for reduced latency
  • Response Size:
    • If the response exceeds the safe payload limit, a 413 error is returned
    • Use the fields parameter, reduce size to limit response size, or use a batch endpoint instead
  • Extra Fields:
    • Unknown fields in the request body are rejected (HTTP 400)

Sample Response (200):

{
  "data": {
    "hits": [
      {
        "_index": "tickets-atr-2026",
        "_id": "afe7dc9e2bfffa904e9ff068f291bf5f",
        "_score": null,
        "_source": {
          "ticket": {
            "description": "Email Distribution List - Add/Remove Users"
          }
        },
        "sort": [1774412848000]
      }
    ],
    "total": 5234,
    "count": 1000
  },
  "meta": {
    "trace_id": "1-69c36684-6c0f659437a3dc38138a02dd",
    "rate_limit": {
      "daily_remaining": 9950
    },
    "pagination": {
      "pit_id": "FGluY2x1ZGVfY29udGV4...",
      "search_after": [1774038927000]
    }
  }
}

Response Fields:

  • data.hits (array): Array of ticket documents
    • _index (string): OpenSearch index name
    • _id (string): Unique ticket identifier
    • _source (object): Ticket content (fields vary based on fields parameter; all fields returned if not specified)
    • sort (array): Sort values used for pagination
  • data.total (integer): Total number of tickets matching the query
  • data.count (integer): Number of tickets returned in this page
  • meta.trace_id (string): X-Ray trace ID for debugging
  • meta.rate_limit.daily_remaining (integer): Remaining API calls for the day
  • meta.pagination.pit_id (string or null): Point in Time ID for next page (null when last page reached)
  • meta.pagination.search_after (array or null): Sort values for next page (null when last page reached)

Last Page: When the last page is reached, pit_id and search_after will both be null. The Point in Time is automatically cleaned up — no additional action is needed.

Common Ticket Fields:

  • ticket.id - Unique ticket identifier
  • ticket.number - Ticket number (e.g., "RITM1098163")
  • ticket.type - Ticket type (e.g., "SR_ITEM")
  • ticket.short_description - Brief description
  • ticket.state - Current state (e.g., "Requested")
  • ticket.priority - Priority level (e.g., "4 - Low")
  • ticket.resolved - Whether the ticket is resolved (boolean)
  • ticket.mapped - Whether the ticket is mapped (boolean)
  • ticket.created_on - Creation timestamp
  • ticket.last_updated_on - Last update timestamp
  • atr.domain_name - Domain name
  • atr.infra_type - Infrastructure type ("ec2", "kubernetes")
  • atr.client - Client name
  • atr.environment - Environment (e.g., "client_production")
  • @timestamp - Document timestamp
POST     /v3/tickets/aggs

Description: Retrieve aggregated statistics and analytics from tickets using OpenSearch aggregation queries. Supports terms aggregations, histograms, metrics, and nested aggregations for analyzing ticket patterns.

Request Body:

{
  "application": "atr",
  "app_type": ["ec2", "kubernetes"],
  "domain": ["your-domain.example.com"],
  "start_time": "2026-01-01T00:00:00Z",
  "end_time": "2026-03-20T23:59:59Z",
  "includes_eu": false,
  "aggs": {
    "tickets_by_type": {
      "terms": {
        "field": "ticket.type",
        "size": 20
      }
    },
    "tickets_over_time": {
      "date_histogram": {
        "field": "@timestamp",
        "fixed_interval": "1d"
      }
    },
    "resolved_count": {
      "filter": {
        "term": {"ticket.resolved": true}
      }
    }
  }
}

Request Body (With Filters):

{
  "application": "atr",
  "app_type": ["kubernetes"],
  "domain": ["*"],
  "start_time": "2026-01-01T00:00:00Z",
  "end_time": "2026-03-27T23:59:59Z",
  "includes_eu": true,
  "filters": [
    {"term": {"ticket.type": "INCIDENT"}},
    {"range": {"ticket.priority": {"lte": 2}}}
  ],
  "aggs": {
    "by_priority": {
      "terms": {
        "field": "ticket.priority",
        "size": 10
      }
    },
    "by_domain": {
      "terms": {
        "field": "atr.domain_name",
        "size": 20
      },
      "aggs": {
        "by_state": {
          "terms": {
            "field": "ticket.state",
            "size": 5
          }
        }
      }
    }
  }
}

Required Fields:

  • application (string): Application name. Only "atr" is supported
  • start_time (string): Start time in ISO 8601 format (e.g., "2026-01-19T00:00:00Z" or "2026-01-19T00:00:00.000Z")
  • end_time (string): End time in ISO 8601 format
  • app_type (array): Application types. Options: "ec2", "kubernetes" (e.g., ["ec2"] or ["ec2", "kubernetes"])
  • domain (array): List of domain names or ["*"] for all (cannot be empty)
  • aggs (object): OpenSearch aggregation definition (must contain at least one aggregation)

Optional Fields:

  • filters (array): List of OpenSearch filter objects to apply. See OpenSearch Query DSL for full syntax. Supported filter types:
    • term - Exact match on a field
    • terms - Match any of multiple values
    • range - Numeric or date range queries
    • exists - Check if a field exists
    • bool - Combine filters with nested logic (must, should, must_not)
    • match / match_phrase - Full-text search
  • includes_eu (boolean): Include EU region search (default: true). Set to false to query only the local region for faster response times

Aggregation Types:

The aggs field accepts any valid OpenSearch aggregation. Common types include:

  • Terms Aggregation - Group by field values:
"aggs": {"by_type": {"terms": {"field": "ticket.type","size": 20}}}
  • Date Histogram - Group by time intervals:
"aggs": {"over_time": {"date_histogram": {"field": "@timestamp","fixed_interval": "1d"}}}
  • Filter Aggregation - Count documents matching criteria:
"aggs": {"resolved_tickets": {"filter": {"term": {"ticket.resolved": true}}}}
  • Nested Aggregations - Combine multiple aggregations:
"aggs": {"by_domain": {"terms": {"field": "atr.domain_name","size": 10},"aggs": {"by_type": {"terms": {"field": "ticket.type","size": 5}}}}}
  • Filter with Sub-aggregations - Analyze subset of data:
"aggs": {"incident_analysis": {"filter": {"term": {"ticket.type": "INCIDENT"}},"aggs": {"daily_counts": {"date_histogram": {"field": "@timestamp","fixed_interval": "1d"}}}}}

See OpenSearch Aggregations for full syntax.

Special Rules:

  • App Type Field:
    • Must be a list (e.g., ["ec2"] not "ec2")
    • Only "ec2" and "kubernetes" are valid values
  • Domain Field:
    • Must be a list of strings
    • Cannot be empty
    • When using "*", it must be the only element: ["*"]
    • Cannot mix wildcard with other values: ["*", "domain1"]
  • Cross Region Search:
    • By default (includes_eu: true), the query searches across all regional databases, including EU
    • Set includes_eu: false to query only the local region for reduced latency
  • Time Range:
    • end_time must be after start_time
    • No maximum time range limit
  • Extra Fields:
    • Unknown fields in the request body are rejected (HTTP 400)

Sample Response (200):

{
  "data": {
    "aggregations": {
      "tickets_by_type": {
        "doc_count_error_upper_bound": 0,
        "sum_other_doc_count": 1250,
        "buckets": [
          {"key": "SR_ITEM", "doc_count": 45231},
          {"key": "INCIDENT", "doc_count": 32187},
          {"key": "SR_TASK", "doc_count": 18456}
        ]
      },
      "tickets_over_time": {
        "buckets": [
          {"key_as_string": "2026-01-01T00:00:00.000Z", "key": 1735689600000, "doc_count": 1523},
          {"key_as_string": "2026-01-02T00:00:00.000Z", "key": 1735776000000, "doc_count": 1687}
        ]
      },
      "resolved_count": {
        "doc_count": 67432
      }
    },
    "total": 97124
  },
  "meta": {
    "trace_id": "1-69c36684-6c0f659437a3dc38138a02dd",
    "rate_limit": {
      "daily_remaining": 9950
    },
    "pagination": {
      "pit_id": null,
      "search_after": null
    }
  }
}

Response Fields:

  • data.aggregations (object): Aggregation results - structure varies based on your aggregation definition
    • For terms aggregations: Contains buckets array with key and doc_count
    • For date histograms: Contains buckets array with key_as_string, key, and doc_count
    • For filter aggregations: Contains doc_count number
    • For nested aggregations: Contains nested aggregation results
  • data.total (integer): Total number of tickets matching the query (before aggregation)
  • meta.trace_id (string): X-Ray trace ID for debugging
  • meta.rate_limit.daily_remaining (integer): Remaining API calls for the day
  • meta.pagination.pit_id (null): Always null for aggregation queries (no pagination)
  • meta.pagination.search_after (null): Always null for aggregation queries (no pagination)

Common Ticket Fields for Aggregations:

  • ticket.type - Ticket type (e.g., "SR_ITEM", "INCIDENT", "SR_TASK")
  • ticket.state - Current state (e.g., "Requested", "Closed")
  • ticket.priority - Priority level (e.g., "4 - Low")
  • ticket.resolved - Whether the ticket is resolved (boolean)
  • ticket.mapped - Whether the ticket is mapped (boolean)
  • atr.domain_name - Domain name
  • atr.infra_type - Infrastructure type ("ec2", "kubernetes")
  • atr.client - Client name
  • atr.environment - Environment (e.g., "client_production")
  • @timestamp - Document timestamp

You can also explore available fields using OpenSearch Dashboards Discover.

POST     /v3/tickets/mappings

Description: Retrieve all available fields and their data types from the tickets index. Useful for discovering which fields can be used in filters, fields, and aggs parameters.

Request Body:

{
  "includes_eu": false
}

Optional Fields:

  • includes_eu (boolean): Include EU cross-cluster indices (default: true). Set to false to query only the local region

Special Rules:

  • Extra Fields:
    • Unknown fields in the request body are rejected (HTTP 400)
  • An empty body or {} is valid and defaults to includes_eu: true

Sample Response (200):

{
  "data": {
    "fields": [
      {"name": "@timestamp", "type": "alias"},
      {"name": "atr.client", "type": "keyword"},
      {"name": "atr.domain_name", "type": "keyword"},
      {"name": "atr.infra_type", "type": "keyword"},
      {"name": "ticket.created_on", "type": "date"},
      {"name": "ticket.number", "type": "keyword"},
      {"name": "ticket.priority", "type": "keyword"},
      {"name": "ticket.resolved", "type": "boolean"},
      {"name": "ticket.state", "type": "keyword"},
      {"name": "ticket.type", "type": "keyword"}
    ],
    "field_count": 95
  },
  "meta": {
    "trace_id": "1-69c36684-6c0f659437a3dc38138a02dd",
    "rate_limit": {
      "daily_remaining": 998
    }
  }
}

Response Fields:

  • data.fields (array): Array of field objects, sorted alphabetically by name
    • name (string): Full field path (e.g., "ticket.created_on")
    • type (string): OpenSearch field type (e.g., "keyword", "text", "date", "float", "boolean", "long", "integer", "alias")
  • data.field_count (integer): Total number of fields
  • meta.trace_id (string): X-Ray trace ID for debugging
  • meta.rate_limit.daily_remaining (integer): Remaining API calls for the day

Notes:

  • Fields with multi-field mappings appear as separate entries (e.g., ticket.short_description as keyword and ticket.short_description.text as text)
  • Use keyword type fields for exact match filters (term, terms) and aggregations
  • Use text type fields for full-text search (match, match_phrase)
  • Use date type fields for time-based range queries and date histogram aggregations

Billing​

V1
POST     /v1/query

Description: Query billing data for a specific domain.

Request Body:

{
  "domain": "example.domain.com",
  "time_range": "now-15m/m"
}

Required Fields:

  • domain (string): Domain name of the monitored environment
  • time_range (string): Time range in OpenSearch format (e.g., 'now-15m/m')

Response (200):

{
  "summary": {
    "ticket_count": 125,
    "domain": "example.domain.com",
    "time_range": "now-15m/m",
    "client": "CMClient",
    "live_status": "active",
    "WBS": "1234ABCD",
    "created": "2025-11-11T12:00:00Z",
    "infra_type": "EC2",
    "billing_type": "monthly",
    "point_of_contact": "team@example.com"
  },
  "daily_requests_remaining": 480
}

Rate Limits​

The API implements daily request limits to ensure safe usage:

  • Each successful response includes a daily_requests_remaining field
  • Monitor this value to track your remaining quota
  • Rate limit exceeded requests return HTTP 429 status

Authentication​

All endpoints require JWT authentication. Include your token in the Authorization header.

For detailed authentication setup and examples, see Authentication.