# Find integration setup failures

> Show where customers fail while connecting integrations so engineering and CS can fix the highest-impact setup blockers.

## Agent adaptation contract

- Canonical human page: https://agentry.sh/workflows/integration-setup-failures
- Execution mode: on_demand
- Immutable automation template: none
- Applies to: b2b-saas, devtools-api, open-source
- Required example events: integration_setup_started, integration_setup_failed, integration_setup_succeeded
- Required Agentry resources: none declared
- Do not use when:
  - Do not use until the example events are mapped to observed project signals, the current onboarding state is verified, and live event/property reads prove the required data is present.
- Ask before using:
  - Which observed events map to integration_setup_started, integration_setup_failed, integration_setup_succeeded? Is the current onboarding state verified, and do live event/property reads show non-synthetic traffic for them?
  - Which live properties provide integration_setup_started.account_id, integration_setup_started.integration_type, integration_setup_failed.account_id, integration_setup_failed.integration_type, integration_setup_failed.setup_step, integration_setup_failed.error_code, integration_setup_succeeded.account_id, integration_setup_succeeded.integration_type, and which stable user or account identifier joins the signals?

This is an adaptable workflow example, not an API recipe. Map event and property names to the project's saved signal map, require status: "verified" from GET /v1/projects/:project_id/onboarding, and confirm the required signals through live event/property metadata and rows. Fetch current OpenAPI or query-blueprint details before making calls. Do not infer unattended authority from this page.

## Why this matters

Integrations are often the real activation moment for B2B and devtool products. A failed setup is not just a bug; it is a stalled customer.

## What you get

- Setup failure rate by integration
- The step and error code causing the most blocked accounts
- A short list of accounts CS should help
- Engineering actions ranked by affected accounts

## Walk through it

**You:**
> Which integrations are failing during setup?

**Agent:**
> I'll compare setup starts, failures, and completions by integration and setup step.

```text
Endpoint: POST /v1/projects/:project_id/analytics/query
Exact shape: /v1/openapi.json?path=%2Fv1%2Fprojects%2F%7Bproject_id%7D%2Fanalytics%2Fquery&method=post
Custom HogQL goes in the OpenAPI-defined `query` field.
Concept fields:
  query: "SELECT properties.integration_type AS integration, properties.setup_step AS step, properties.error_code AS error_code, count() AS failures, count(DISTINCT properties.account_id) AS accounts FROM events WHERE event = 'integration_setup_failed' AND timestamp > now() - INTERVAL 30 DAY GROUP BY integration, step, error_code ORDER BY accounts DESC, failures DESC LIMIT 20"
```

```text
{
  "rows": [
    { "integration": "salesforce", "step": "oauth_callback", "error_code": "invalid_scope", "failures": 42, "accounts": 17 }
  ]
}
```

**Agent:**
> Salesforce OAuth scope failures are blocking 17 accounts. I'll check whether any open cases match this pattern.

```text
Endpoint: GET /v1/projects/:project_id/cases
Exact shape: /v1/openapi.json?path=%2Fv1%2Fprojects%2F%7Bproject_id%7D%2Fcases&method=get
Use query parameters, not a JSON body.
Query/filter concept:
  status: "open"
```

## The output

The agent returns the integrations, setup steps, error codes, and affected-account counts that deserve action first. It should separate product-copy fixes from backend defects and CS follow-up.

## Setting it up

Emit setup lifecycle events for each integration. Include the account, integration name, setup step, and normalized error code so failures can be grouped cleanly.

## Variations

- *"Which integration setup failures affect enterprise accounts?"*
- *"Show failed setup by integration version."*
- *"Draft a CS follow-up list for blocked accounts."*