# Retrieve health metrics for a data connector

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.
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.

Endpoint: GET /data_connectors/{data_connector_id}/health
Version: Preview
Security: bearerAuth

## Path parameters:

  - `data_connector_id` (string, required)
    The unique identifier for the data connector.

## Query parameters:

  - `start_ts` (integer)
    Unix timestamp for the start of the time range. Defaults to 7 days before `end_ts`.

  - `end_ts` (integer)
    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.

  - `bucket_size_minutes` (integer)
    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.

## Header parameters:

  - `Intercom-Version` (string)

## Response 200 fields (application/json):

  - `type` (string)
    The type of object - `data_connector_health`.
    Enum: "data_connector_health"

  - `start_ts` (integer)
    Unix timestamp marking the start of the time range this report covers.
    Example: 1755000000

  - `end_ts` (integer)
    Unix timestamp marking the end of the time range this report covers.
    Example: 1755604800

  - `bucket_size_minutes` (integer)
    The width, in minutes, of each interval in `time_series`.
    Example: 34

  - `summary` (object)
    Aggregate health metrics for the requested time range.

  - `summary.total_executions` (integer)
    The total number of executions in the requested time range.
    Example: 1420

  - `summary.success_rate` (number)
    The proportion of executions that completed and returned a 2xx status, as a decimal between 0.0 and 1.0.
    Example: 0.9754

  - `summary.overall_status` (string)
    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"

  - `summary.external_latency_ms` (object)
    Latency percentiles, in milliseconds, for time spent waiting on the external service this connector calls.

  - `summary.external_latency_ms.p50` (integer)
    The 50th percentile (median) value.
    Example: 120

  - `summary.external_latency_ms.p90` (integer)
    The 90th percentile value.
    Example: 340

  - `summary.external_latency_ms.p99` (integer)
    The 99th percentile value.
    Example: 890

  - `summary.internal_latency_ms` (object)
    Latency percentiles, in milliseconds, for time Intercom spent processing each execution, excluding time spent waiting on the external service.

  - `summary.response_payload_size_bytes` (object)
    Response payload size percentiles, in bytes, for the external service's responses.

  - `summary.http_status_distribution` (array)
    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`.

  - `summary.http_status_distribution.http_status` (integer)
    The HTTP status code returned by the external service.
    Example: 200

  - `summary.http_status_distribution.count` (integer)
    The number of executions that received this status code.
    Example: 1385

  - `summary.failure_types_distribution` (array)
    A breakdown of failed executions by failure reason, ordered by count descending.

  - `summary.failure_types_distribution.error_type` (string)
    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

  - `summary.failure_types_distribution.count` (integer)
    The number of executions that failed for this reason.
    Example: 22

  - `time_series` (array)
    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.

  - `time_series.bucket_start` (integer)
    Unix timestamp marking the start of this interval.
    Example: 1754999760

  - `time_series.execution_count` (integer)
    The number of executions in this interval.
    Example: 12

  - `time_series.external_latency_avg_ms` (integer)
    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

  - `time_series.external_latency_max_ms` (integer)
    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

  - `time_series.internal_latency_avg_ms` (integer)
    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

  - `time_series.internal_latency_max_ms` (integer)
    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

## Response 400 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (any, required)
    A string indicating the kind of error, used to further qualify the HTTP response code. A few request validation errors send an HTTP status code as an integer here instead, for example `422`.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

## Response 401 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (any, required)
    A string indicating the kind of error, used to further qualify the HTTP response code. A few request validation errors send an HTTP status code as an integer here instead, for example `422`.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

## Response 404 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (any, required)
    A string indicating the kind of error, used to further qualify the HTTP response code. A few request validation errors send an HTTP status code as an integer here instead, for example `422`.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid