From f22f291b94a3a8e231bd5fedecd377a966454f64 Mon Sep 17 00:00:00 2001 From: Zille Eizad Date: Fri, 21 Aug 2026 12:27:52 +0100 Subject: [PATCH 1/5] Add the data connector health endpoint to the Preview spec GET /data_connectors/{data_connector_id}/health returns aggregated execution health for a data connector over a requested time range: success rate, latency and payload size percentiles, breakdowns of HTTP statuses and failure reasons, and a time series of intervals. --- descriptions/0/api.intercom.io.yaml | 309 ++++++++++++++++++++++++++++ 1 file changed, 309 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 6067f6b7..04558b6c 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -16429,6 +16429,153 @@ paths: message: Execution result not found schema: "$ref": "#/components/schemas/error" + "/data_connectors/{data_connector_id}/health": + get: + summary: Retrieve health metrics for a data connector + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: data_connector_id + in: path + required: true + description: The unique identifier for the data connector. + schema: + type: string + example: '12345' + - name: start_ts + in: query + required: false + description: Unix timestamp for the start of the time range. Defaults to 7 days before `end_ts`. + schema: + type: integer + - name: end_ts + in: query + required: false + description: Unix timestamp for the end of the time range (default now). + schema: + type: integer + - name: bucket_size_minutes + in: query + required: false + description: Width of each interval in `time_series`, in minutes. Defaults to a width chosen to suit the requested range. + schema: + type: integer + minimum: 1 + maximum: 1440 + tags: + - Data Connectors + operationId: getDataConnectorHealth + description: | + Retrieve aggregated execution health for a data connector: success rate, latency and payload size percentiles, a breakdown of HTTP statuses and failure reasons, and a time series over the requested range. + + Metrics from the last 7 days are returned by default. Use `start_ts` and `end_ts` to set the range, which may span at most 14 days. How far back data is available depends on your workspace's data connector log retention. + + Responses are cached briefly, so consecutive calls may return identical data. + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + type: data_connector_health + start_ts: 1755000000 + end_ts: 1755604800 + bucket_size_minutes: 34 + summary: + total_executions: 1420 + success_rate: 0.9754 + overall_status: healthy + external_latency_ms: + p50: 120 + p90: 340 + p99: 890 + internal_latency_ms: + p50: 18 + p90: 42 + p99: 96 + response_payload_size_bytes: + p50: 2048 + p90: 8192 + p99: 20480 + http_status_distribution: + - http_status: 200 + count: 1385 + - http_status: 500 + count: 35 + failure_types_distribution: + - error_type: faraday_error + count: 22 + - error_type: response_mapping_error + count: 13 + time_series: + - bucket_start: 1755000000 + execution_count: 12 + external_latency_avg_ms: 133 + external_latency_max_ms: 402 + internal_latency_avg_ms: 21 + internal_latency_max_ms: 58 + schema: + "$ref": "#/components/schemas/data_connector_health" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '400': + description: Invalid parameter + content: + application/json: + examples: + Inverted time range: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: parameter_invalid + message: end_ts must not be before start_ts + Time range too long: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: parameter_invalid + message: the requested window may not exceed 336 hours + Invalid bucket size: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: parameter_invalid + message: bucket_size_minutes must be between 1 and 1440 + schema: + "$ref": "#/components/schemas/error" + '404': + description: Data connector not found + content: + application/json: + examples: + Data connector not found: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: data_connector_not_found + message: Data connector not found + schema: + "$ref": "#/components/schemas/error" "/ecommerce/connectors/{id}/catalog": post: summary: Upload a product catalog @@ -32999,6 +33146,168 @@ components: type: string description: The cursor value to use for the next page. example: WzE3MDc1OTQ3MTUuMCw5OTAwMF0= + data_connector_health: + title: Data Connector Health + type: object + x-tags: + - Data Connectors + description: Aggregated execution health for a data connector over a time range. + properties: + type: + type: string + description: The type of object - `data_connector_health`. + enum: + - data_connector_health + example: data_connector_health + start_ts: + type: integer + description: Unix timestamp marking the start of the time range this report covers. + example: 1755000000 + end_ts: + type: integer + description: Unix timestamp marking the end of the time range this report covers. + example: 1755604800 + bucket_size_minutes: + type: integer + description: The width, in minutes, of each interval in `time_series`. + example: 34 + summary: + "$ref": "#/components/schemas/data_connector_health_summary" + time_series: + type: array + description: Intervals covering the requested time range, ordered oldest first. An interval with no executions is omitted rather than returned with zero counts. + items: + "$ref": "#/components/schemas/data_connector_health_time_series_point" + data_connector_health_summary: + title: Data Connector Health Summary + type: object + x-tags: + - Data Connectors + description: Aggregate health metrics for the requested time range. + properties: + total_executions: + type: integer + description: The total number of executions in the requested time range. + example: 1420 + success_rate: + type: number + description: The proportion of executions that completed successfully, as a decimal between 0.0 and 1.0. + example: 0.9754 + overall_status: + type: string + nullable: true + description: A high-level health signal for the requested time range. This is an advisory heuristic that Intercom may retune, not a stable classification - build on `success_rate` and the latency percentiles if you need consistent behaviour across changes. Null when the range contains no executions. + enum: + - healthy + - degraded + - unhealthy + example: healthy + external_latency_ms: + description: Latency percentiles, in milliseconds, for time spent waiting on the external service this connector calls. + allOf: + - "$ref": "#/components/schemas/data_connector_health_percentiles" + internal_latency_ms: + description: Latency percentiles, in milliseconds, for time Intercom spent processing each execution, excluding time spent waiting on the external service. + allOf: + - "$ref": "#/components/schemas/data_connector_health_percentiles" + response_payload_size_bytes: + description: Response payload size percentiles, in bytes, for the external service's responses. + allOf: + - "$ref": "#/components/schemas/data_connector_health_percentiles" + http_status_distribution: + type: array + description: A breakdown of executions by the HTTP status code returned, ordered by status code ascending. + items: + "$ref": "#/components/schemas/data_connector_health_status_count" + failure_types_distribution: + type: array + description: A breakdown of failed executions by failure reason, ordered by count descending. + items: + "$ref": "#/components/schemas/data_connector_health_failure_count" + data_connector_health_percentiles: + title: Data Connector Health Percentiles + type: object + x-tags: + - Data Connectors + description: Percentile values computed over successful executions. Each is null when no successful execution in the range carried the measurement. + properties: + p50: + type: integer + nullable: true + description: The 50th percentile (median) value. + example: 120 + p90: + type: integer + nullable: true + description: The 90th percentile value. + example: 340 + p99: + type: integer + nullable: true + description: The 99th percentile value. + example: 890 + data_connector_health_status_count: + title: Data Connector Health Status Count + type: object + x-tags: + - Data Connectors + description: The number of executions that received a given HTTP status code. + properties: + http_status: + type: integer + description: The HTTP status code returned by the external service. + example: 200 + count: + type: integer + description: The number of executions that received this status code. + example: 1385 + data_connector_health_failure_count: + title: Data Connector Health Failure Count + type: object + x-tags: + - Data Connectors + description: The number of executions that failed for a given reason. + properties: + error_type: + type: string + nullable: true + description: A machine-readable failure reason, using the same vocabulary as the `error_type` field and filter on the execution results endpoint - a value returned here can be used directly as that filter. Null when the failed execution carried no recorded reason. + example: faraday_error + count: + type: integer + description: The number of executions that failed for this reason. + example: 22 + data_connector_health_time_series_point: + title: Data Connector Health Time Series Point + type: object + x-tags: + - Data Connectors + description: Execution metrics for one interval of the requested time range. + properties: + bucket_start: + type: integer + description: Unix timestamp marking the start of this interval. + example: 1755000000 + execution_count: + type: integer + description: The number of executions in this interval. + example: 12 + external_latency_avg_ms: + type: integer + description: The average time, in milliseconds, spent waiting on the external service across executions in this interval. + example: 133 + external_latency_max_ms: + type: integer + description: The highest time, in milliseconds, spent waiting on the external service in this interval. + example: 402 + internal_latency_avg_ms: + type: integer + description: The average time, in milliseconds, Intercom spent processing executions in this interval. + example: 21 + internal_latency_max_ms: + type: integer + description: The highest time, in milliseconds, Intercom spent processing an execution in this interval. + example: 58 data_connector_list: title: Data Connector List type: object From b68f530557519166780b3640a8be1884bd68c3be Mon Sep 17 00:00:00 2001 From: Zille Eizad Date: Thu, 27 Aug 2026 17:04:17 +0100 Subject: [PATCH 2/5] Report an unrecorded failure reason as unknown rather than null --- descriptions/0/api.intercom.io.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 04558b6c..a7f0deb7 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -33270,8 +33270,7 @@ components: properties: error_type: type: string - nullable: true - description: A machine-readable failure reason, using the same vocabulary as the `error_type` field and filter on the execution results endpoint - a value returned here can be used directly as that filter. Null when the failed execution carried no recorded reason. + description: A machine-readable failure reason. Values match the `error_type` field on the execution results endpoint, plus `unknown` for a failed execution that recorded no reason. example: faraday_error count: type: integer From 2983ecf08ccc5117c6e49a495d34f1b89cd6f9db Mon Sep 17 00:00:00 2001 From: Zille Eizad Date: Tue, 3 Nov 2026 14:36:21 +0000 Subject: [PATCH 3/5] Describe health metrics behaviour the first pass left implicit Six details a developer would otherwise have to discover by calling the endpoint: - The default `bucket_size_minutes` divides the range into 300 intervals or fewer, rather than "a width chosen to suit the range". - Interval boundaries align to multiples of the width from the Unix epoch, not to `start_ts`, so the first interval may begin before `start_ts`. - A time-series latency field reports 0 when nothing in that interval carried the measurement, which is indistinguishable from a true zero. - An execution counts as successful only when it completed AND returned a 2xx status; one with no recorded status counts as a failure and appears under `unknown`. - `http_status_distribution` omits executions with no recorded status, so its counts may add up to less than `total_executions`. - Responses are cached for up to a minute. The 200 example's `bucket_start` moves to an epoch-aligned value so it illustrates the alignment rule rather than contradicting it. Co-Authored-By: Claude Opus 5 --- descriptions/0/api.intercom.io.yaml | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index a7f0deb7..7fbf9c34 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -16459,7 +16459,7 @@ paths: - name: bucket_size_minutes in: query required: false - description: Width of each interval in `time_series`, in minutes. Defaults to a width chosen to suit the requested range. + description: Width of each interval in `time_series`, in minutes. Defaults to the narrowest whole number of minutes that divides the requested range into 300 intervals or fewer. schema: type: integer minimum: 1 @@ -16472,7 +16472,9 @@ paths: Metrics from the last 7 days are returned by default. Use `start_ts` and `end_ts` to set the range, which may span at most 14 days. How far back data is available depends on your workspace's data connector log retention. - Responses are cached briefly, so consecutive calls may return identical data. + An execution counts as successful when it completed and the external service returned a 2xx status. An execution that recorded no HTTP status counts as a failure, and appears in `failure_types_distribution` under `unknown`. + + Responses are cached for up to a minute, so consecutive calls may return identical data. responses: '200': description: successful @@ -16512,7 +16514,7 @@ paths: - error_type: response_mapping_error count: 13 time_series: - - bucket_start: 1755000000 + - bucket_start: 1754999760 execution_count: 12 external_latency_avg_ms: 133 external_latency_max_ms: 402 @@ -33175,7 +33177,7 @@ components: "$ref": "#/components/schemas/data_connector_health_summary" time_series: type: array - description: Intervals covering the requested time range, ordered oldest first. An interval with no executions is omitted rather than returned with zero counts. + description: Intervals covering the requested time range, ordered oldest first. Interval boundaries are aligned to multiples of `bucket_size_minutes` from the Unix epoch rather than to `start_ts`, so the first interval may begin before `start_ts`. An interval with no executions is omitted rather than returned with zero counts. items: "$ref": "#/components/schemas/data_connector_health_time_series_point" data_connector_health_summary: @@ -33191,7 +33193,7 @@ components: example: 1420 success_rate: type: number - description: The proportion of executions that completed successfully, as a decimal between 0.0 and 1.0. + description: The proportion of executions that completed and returned a 2xx status, as a decimal between 0.0 and 1.0. example: 0.9754 overall_status: type: string @@ -33216,7 +33218,7 @@ components: - "$ref": "#/components/schemas/data_connector_health_percentiles" http_status_distribution: type: array - description: A breakdown of executions by the HTTP status code returned, ordered by status code ascending. + description: A breakdown of executions by the HTTP status code returned, ordered by status code ascending. An execution that recorded no HTTP status is absent, so these counts may add up to less than `total_executions`. items: "$ref": "#/components/schemas/data_connector_health_status_count" failure_types_distribution: @@ -33286,26 +33288,26 @@ components: bucket_start: type: integer description: Unix timestamp marking the start of this interval. - example: 1755000000 + example: 1754999760 execution_count: type: integer description: The number of executions in this interval. example: 12 external_latency_avg_ms: type: integer - description: The average time, in milliseconds, spent waiting on the external service across executions in this interval. + description: The average time, in milliseconds, spent waiting on the external service across executions in this interval. Reported as 0 when no execution in this interval carried the measurement. example: 133 external_latency_max_ms: type: integer - description: The highest time, in milliseconds, spent waiting on the external service in this interval. + description: The highest time, in milliseconds, spent waiting on the external service in this interval. Reported as 0 when no execution in this interval carried the measurement. example: 402 internal_latency_avg_ms: type: integer - description: The average time, in milliseconds, Intercom spent processing executions in this interval. + description: The average time, in milliseconds, Intercom spent processing executions in this interval. Reported as 0 when no execution in this interval carried the measurement. example: 21 internal_latency_max_ms: type: integer - description: The highest time, in milliseconds, Intercom spent processing an execution in this interval. + description: The highest time, in milliseconds, Intercom spent processing an execution in this interval. Reported as 0 when no execution in this interval carried the measurement. example: 58 data_connector_list: title: Data Connector List From 213abd848b2e87e5f03b7200601e831bc5c032cb Mon Sep 17 00:00:00 2001 From: Zille Eizad Date: Wed, 4 Nov 2026 09:41:59 +0000 Subject: [PATCH 4/5] Document the interval cap and the minute-floored default window end Co-Authored-By: Claude Opus 5 --- descriptions/0/api.intercom.io.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index a0300ab4..4e341065 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -25637,13 +25637,13 @@ paths: - name: end_ts in: query required: false - description: Unix timestamp for the end of the time range (default now). + description: Unix timestamp for the end of the time range. Defaults to the current time rounded down to the minute, so the `end_ts` in the response may be up to a minute earlier than the moment you called. schema: type: integer - name: bucket_size_minutes in: query required: false - description: Width of each interval in `time_series`, in minutes. Defaults to the narrowest whole number of minutes that divides the requested range into 300 intervals or fewer. + description: Width of each interval in `time_series`, in minutes. Defaults to the narrowest whole number of minutes that divides the requested range into 300 intervals or fewer. The time range divided by this width may not exceed 2000 intervals, so a narrow width needs a shorter range. schema: type: integer minimum: 1 From bc61a76f7bafb7ee4f0ea91d5f06349704d4ac57 Mon Sep 17 00:00:00 2001 From: Zille Eizad Date: Wed, 4 Nov 2026 15:54:26 +0000 Subject: [PATCH 5/5] Stop claiming a failure without an HTTP status is reported as unknown The failure breakdown is keyed on error_type alone, independent of HTTP status: a timeout records status 0 with error_type faraday_error and is counted under that code. unknown covers only a failure with no recorded reason, which the error_type description already states. Co-Authored-By: Claude Opus 5 --- descriptions/0/api.intercom.io.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 4e341065..272b7b83 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -25656,7 +25656,7 @@ paths: Metrics from the last 7 days are returned by default. Use `start_ts` and `end_ts` to set the range, which may span at most 14 days. How far back data is available depends on your workspace's data connector log retention. - An execution counts as successful when it completed and the external service returned a 2xx status. An execution that recorded no HTTP status counts as a failure, and appears in `failure_types_distribution` under `unknown`. + An execution counts as successful when it completed and the external service returned a 2xx status. An execution that recorded no HTTP status counts as a failure. Responses are cached for up to a minute, so consecutive calls may return identical data. responses: