Find integration setup failures

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

Updated · published

markdown for agents →

difficulty intermediate · time to value 5 minutes · execution on demand
#analytics #errors #integrations #onboarding #customer-success #engineering

Start from this 

Find integration setup failures by integration, setup step, account, and error code. Prioritize blockers affecting the most accounts.

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.

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

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

Related workflows

growth 5 minutes

Which doc page leads to the most API adoption?

Funnel from a docs page view to first api_request by the same distinct_id within 7 days. Per-doc-page breakdown — find the highest-leverage page in your docs.

debugging 5 minutes

Investigate one customer-reported problem

Review the minimum identity-linked product evidence for an authorized support case, corroborate any real error case, and prepare a reply that preserves uncertainty.

debugging 5 minutes

Find slow API routes by customer and plan

Rank API endpoints by p95 latency, error rate, customer, and plan so engineering can fix performance where it affects revenue.

Adapt this workflow in your own agent.

Ask your agent to map the starter prompt to your saved signal map, live events, and the current HTTP API before answering.

Agentry gives coding agents production context from errors, product analytics, and deploys through one HTTP API. Fetch and read https://agentry.sh/install.md completely, then install Agentry's full first-time telemetry baseline in this repository. I authorize device-code login, saving the owner key only to ~/.agentry/credentials.json, creating one Agentry project for this repository, and read-only inspection of shipped source plus hidden CI/provider configuration. Deeply analyze the product's business logic and complete value flow before choosing telemetry. Save the complete source-backed plan and show me its exact contents and hash. Until I explicitly approve that plan or request a replacement, do not edit app/CI source, place runtime/CI credentials, commit, exercise product traffic, start proof, push, or deploy. After approval, I authorize only the reviewed targets: place the required scoped browser/server/CI credentials through the established environment or secret mechanism, preserve existing telemetry, implement and test the baseline, commit it, push that reviewed commit when the shipped CI/provider path requires it, exercise safe proof paths with test/non-customer data, and perform one deployment through the reviewed shipped CI/provider path. Ask first if proof would charge money, contact a third party, change real customer data, or require new external access. After the plan is saved, immediately before every onboarding state-changing POST, GET current onboarding state, perform only its single returned next_action, then read state again; do not batch or infer later stages. Continue until status is verified, installation_complete is true, and next_action is null. Keep all secrets, source snapshots, proof markers, and scratch files outside the repository.

+ Full access
5.5 Extra High
  1. 1. Open your repo in Codex, Claude Code, Cursor etc.
  2. 2. Paste the install prompt.
  3. 3. Your agent reads the install doc and shows you an implementation plan for approval.
← all workflows