SpiderAPI Docs
Revenue Intelligence Layer
Recovery Engine

Spider API

Spider is a revenue intelligence and recovery API for brokerages and trading platforms.

It ingests account and activity data, detects lifecycle gaps across your user base, and automatically triggers recovery actions — including email, notifications, and future multi-channel engagement.

From detection to action — Spider closes the loop.

Base URL

https://api.spider.ai

API Version

v1 · Recovery Actions

Supports real-time recovery actions and lifecycle automation.

Auth

X-API-Key header

Integration path

Ingest Accounts→Ingest Activities→Detect Leaks→Prioritize→Act→Track Outcomes

Quickstart

15 min

Start detecting revenue leaks in three steps.

Spider works by ingesting account and activity data, then exposing prioritized recovery signals across lifecycle gaps.

Integration flow

Broker data→Spider ingestion→Lifecycle normalization→Leak detection→Prioritization→Revenue recovery
1

Authenticate requests

All Spider API requests require an API key passed in the request header.

bash
curl -X GET "https://api.spider.ai/api/v1/source-leaks/prioritized" \
  -H "X-API-Key: your_api_key_here"
2

Ingest account and activity data

Send account snapshots and activity records to Spider using the source ingestion endpoints.

Ingestion endpoints

POST/api/v1/source-accounts
POST/api/v1/source-accounts/bulk
POST/api/v1/source-activities
POST/api/v1/source-activities/bulk
3

Fetch prioritized revenue leaks

bash
curl -X GET "https://api.spider.ai/api/v1/source-leaks/prioritized" \
  -H "X-API-Key: your_api_key_here"
json
{
  "items": [
    {
      "external_account_id": "acc_high_value_inactive_001",
      "leak_type": "inactive_trader",
      "severity_score": 92,
      "severity_label": "high",
      "estimated_revenue_loss": 75.0,
      "estimated_recovery_value": 175.0,
      "action_priority": "urgent",
      "action_channel": "advisor",
      "action_message": "Previously active trader has been inactive for 95 days."
    }
  ],
  "count": 6,
  "rule": "prioritized_leaks"
}

Authentication

All Spider API requests require an API key passed as a request header. Never expose your key in client-side code.

ℹ
API keys are scoped to your tenant. Rotate keys immediately if compromised. Contact support to generate a new key.
ParameterTypeRequiredDescription
X-API-KeystringRequiredYour secret API key obtained from the Spider dashboard.
Content-TypestringOptionalRequired for POST requests: application/json
bash
curl -X GET "https://api.spider.ai/api/v1/source-leaks/prioritized" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxx"

Ingest Event

Legacy

Submit a single user lifecycle event for real-time signal detection.

⚠
This endpoint is maintained for backward compatibility. New integrations should use /source-accounts and /source-activities instead.
POST/api/v1/events
ParameterTypeRequiredDescription
eventstringRequiredEvent type: deposit_completed, trade_executed, kyc_approved, etc.
user_idstringRequiredYour platform's unique user identifier.
amountfloatOptionalTransaction amount where applicable.
timestampISO 8601RequiredWhen the event occurred.
json
{
  "event": "deposit_completed",
  "user_id": "usr_123",
  "amount": 5000,
  "timestamp": "2026-03-24T10:32:00Z"
}

Source Accounts (Single)

Ingest a single raw source account payload into Spider.

POST/api/v1/source-accounts
ParameterTypeRequiredDescription
payloadobjectRequiredRaw account object from your source system.
payload.idstringRequiredYour platform's unique account identifier.
payload.statusstringRequiredAccount status string from the source system (e.g. ACTIVE, ONBOARDING).
payload.cashstringOptionalCash balance as a string.
payload.portfolio_valuestringOptionalTotal portfolio value as a string.
bash
curl -X POST "https://api.spider.ai/api/v1/source-accounts" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "payload": {
      "id": "acc_001",
      "account_number": "PA12345678",
      "status": "ACTIVE",
      "cash": "1500.25",
      "portfolio_value": "1500.25"
    }
  }'
json
{
  "accepted": true,
  "source_system": "alpaca",
  "record_type": "source_account",
  "external_id": "acc_001",
  "message": "Source account ingested successfully"
}

Source Accounts (Bulk)

Ingest multiple raw source account payloads in a single request.

POST/api/v1/source-accounts/bulk
ℹ
For initial platform setup, submit your complete account history via bulk before enabling real-time streaming.
bash
curl -X POST "https://api.spider.ai/api/v1/source-accounts/bulk" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "payloads": [
      { "id": "acc_001", "status": "ACTIVE", "cash": "1500.25" },
      { "id": "acc_002", "status": "ONBOARDING", "cash": "0" }
    ]
  }'
json
{
  "accepted": true,
  "source_system": "alpaca",
  "record_type": "source_account",
  "received": 2,
  "succeeded": 2,
  "failed": 0,
  "message": "Source account bulk ingest completed"
}

Source Activities (Single)

Ingest a single raw source activity payload into Spider.

POST/api/v1/source-activities
ParameterTypeRequiredDescription
payloadobjectRequiredRaw activity object from your source system.
payload.idstringRequiredUnique activity identifier.
payload.account_idstringRequiredThe account this activity belongs to.
payload.activity_typestringRequiredActivity type from source (e.g. FILL, CSD).
payload.transaction_timeISO 8601OptionalWhen the activity occurred.
bash
curl -X POST "https://api.spider.ai/api/v1/source-activities" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "payload": {
      "id": "activity_001",
      "account_id": "acc_001",
      "activity_type": "FILL",
      "transaction_time": "2026-04-09T15:43:18.488000Z",
      "symbol": "AAPL",
      "qty": "1",
      "price": "180.50",
      "type": "fill"
    }
  }'
json
{
  "accepted": true,
  "source_system": "alpaca",
  "record_type": "source_activity",
  "external_id": "activity_001",
  "message": "Source activity ingested successfully"
}

Source Activities (Bulk)

Ingest multiple raw source activity payloads in a single request.

POST/api/v1/source-activities/bulk
bash
curl -X POST "https://api.spider.ai/api/v1/source-activities/bulk" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "payloads": [
      { "id": "activity_001", "account_id": "acc_001", "activity_type": "FILL", "symbol": "AAPL", "qty": "1", "price": "180.50" },
      { "id": "activity_002", "account_id": "acc_002", "activity_type": "CSD", "net_amount": "1000.00" }
    ]
  }'
json
{
  "accepted": true,
  "source_system": "alpaca",
  "record_type": "source_activity",
  "received": 2,
  "succeeded": 2,
  "failed": 0,
  "message": "Source activity bulk ingest completed"
}

Ingestion Summary

Return source ingestion record counts and freshness indicators for the current tenant.

GET/api/v1/source-ingestion/summary
json
{
  "tenant_id": "quantl-tenant",
  "source_system": "alpaca",
  "accounts": {
    "total": 284,
    "last_updated_at": "2026-03-25T10:00:00+00:00",
    "status": "stale"
  },
  "activities": {
    "total": 3695,
    "last_event_at": "2026-04-09T15:43:18.488000+00:00",
    "status": "stale"
  }
}

Ingestion Checks

Return ingestion completeness and missing-field checks for the current tenant.

GET/api/v1/source-ingestion/checks
json
{
  "tenant_id": "quantl-tenant",
  "source_system": "alpaca",
  "accounts": {
    "total": 284,
    "missing_external_account_id": 0,
    "missing_normalized_status": 0,
    "missing_created_at": 0,
    "missing_raw_payload": 0
  },
  "activities": {
    "total": 3695,
    "missing_external_activity_id": 0,
    "missing_external_account_id": 0,
    "missing_activity_type": 0,
    "missing_event_at": 0,
    "missing_raw_payload": 0
  }
}

Prioritized Leaks

Flagship

Return all detected source-based leaks ranked by operational priority.

Sorted by revenue impact. Highest value first.

GET/api/v1/source-leaks/prioritized
ParameterTypeRequiredDescription
limitintegerOptionalMax results to return. Default: 100.
severitystringOptionalFilter by severity: high, medium, low.
leak_typestringOptionalFilter by type: inactive_trader, funded_no_trade, active_not_funded, idle_cash_no_position.
json
{
  "items": [
    {
      "external_account_id": "8e0006bc-9173-458c-a09e-4e70101e5e4f",
      "normalized_status": "active",
      "lifecycle_stage": "inactive_trader",
      "latest_traded_at": "2026-01-20T14:34:17.727518Z",
      "days_since_last_trade": 80,
      "latest_trade_symbol": "XOM",
      "cash": "-12315.55",
      "portfolio_value": "35879.98",
      "leak_type": "inactive_trader",
      "recommended_action": "send_reactivation_nudge",
      "severity_score": 75,
      "severity_label": "high",
      "estimated_revenue_loss": 107.63994,
      "estimated_recovery_value": 251.15986,
      "action_priority": "urgent",
      "action_channel": "advisor",
      "action_message": "Previously active trader has been inactive for 80 days."
    }
  ],
  "count": 55,
  "rule": "prioritized_leaks"
}

Leak Summary

Return aggregate leak counts and capital-at-risk totals for the current tenant.

GET/api/v1/source-leaks/summary
json
{
  "funded_no_trade": 3,
  "active_not_funded": 30,
  "inactive_trader": 15,
  "idle_cash_no_position": 7,
  "total_leaks": 55,
  "funded_no_trade_capital": 15145.0,
  "inactive_trader_capital": 49931.66,
  "idle_cash_no_position_capital": 10644.1,
  "total_capital_at_risk": 75720.76
}

Funded No Trade

Return funded accounts that have not placed a first trade.

GET/api/v1/source-leaks/funded-no-trade
json
{
  "items": [
    {
      "external_account_id": "231be9a4-ea7d-403e-b059-4a7bd054dd29",
      "normalized_status": "active",
      "lifecycle_stage": "funded_no_trade",
      "cash": "10060.00",
      "portfolio_value": "10060.00",
      "leak_type": "funded_no_trade",
      "recommended_action": "send_first_trade_nudge",
      "severity_score": 55,
      "severity_label": "medium",
      "estimated_revenue_loss": 30.18,
      "estimated_recovery_value": 70.42,
      "action_priority": "normal",
      "action_channel": "email",
      "action_message": "Account is funded with cash available but has not placed a first trade."
    }
  ],
  "count": 3,
  "rule": "funded_no_trade"
}

Active Not Funded

Return active accounts that are approved but not funded.

GET/api/v1/source-leaks/active-not-funded
json
{
  "items": [
    {
      "external_account_id": "1f0e5eaa-1111-4d11-8f22-0a1234567890",
      "normalized_status": "active",
      "lifecycle_stage": "active_not_funded",
      "cash": "0.00",
      "portfolio_value": "0.00",
      "leak_type": "active_not_funded",
      "recommended_action": "send_funding_reminder",
      "severity_score": 30,
      "severity_label": "low",
      "estimated_revenue_loss": 0.0,
      "estimated_recovery_value": 0.0,
      "action_priority": "low",
      "action_channel": "email",
      "action_message": "Account is active but not funded. Send a funding reminder."
    }
  ],
  "count": 30,
  "rule": "active_not_funded"
}

Inactive Traders

Return previously active traders whose last trade is older than the inactivity threshold.

GET/api/v1/source-leaks/inactive-traders
json
{
  "items": [
    {
      "external_account_id": "8e0006bc-9173-458c-a09e-4e70101e5e4f",
      "normalized_status": "active",
      "lifecycle_stage": "inactive_trader",
      "latest_traded_at": "2026-01-20T14:34:17.727518Z",
      "days_since_last_trade": 80,
      "latest_trade_symbol": "XOM",
      "cash": "-12315.55",
      "portfolio_value": "35879.98",
      "leak_type": "inactive_trader",
      "recommended_action": "send_reactivation_nudge",
      "severity_score": 75,
      "severity_label": "high",
      "estimated_revenue_loss": 107.63994,
      "estimated_recovery_value": 251.15986,
      "action_priority": "urgent",
      "action_channel": "advisor",
      "action_message": "Previously active trader has been inactive for 80 days."
    }
  ],
  "count": 15,
  "rule": "inactive_trader"
}

Idle Cash No Position

Return accounts holding cash with no open positions.

GET/api/v1/source-leaks/idle-cash-no-position
json
{
  "items": [
    {
      "external_account_id": "231be9a4-ea7d-403e-b059-4a7bd054dd29",
      "normalized_status": "active",
      "lifecycle_stage": "idle_cash",
      "cash": "10060.00",
      "portfolio_value": "10060.00",
      "leak_type": "idle_cash_no_position",
      "recommended_action": "prompt_capital_deployment",
      "severity_score": 50,
      "severity_label": "medium",
      "estimated_revenue_loss": 30.18,
      "estimated_recovery_value": 70.42,
      "action_priority": "normal",
      "action_channel": "advisor",
      "action_message": "Account has idle cash (10060.00) and no open positions."
    }
  ],
  "count": 7,
  "rule": "idle_cash_no_position"
}

Lifecycle Intelligence

Understand where users are stuck across onboarding and activation lifecycle.

Spider exposes lifecycle visibility across account states such as onboarding, approval pending, action required, active, rejected, and closed. This allows brokers to identify where users drop before becoming revenue-generating customers.

Get Lifecycle Status Summary

Returns distribution of accounts across lifecycle states (KYC and account status).

GET/api/v1/lifecycle/status-summary
bash
curl -X GET "https://api.spiderinfra.com/api/v1/lifecycle/status-summary" \
  -H "x-api-key: YOUR_API_KEY"
json
{
  "total_accounts": 298,
  "source_system": "alpaca",
  "statuses": [
    { "status": "onboarding", "label": "Onboarding", "count": 181 },
    { "status": "approval_pending", "label": "Approval pending", "count": 6 },
    { "status": "action_required", "label": "Action required", "count": 1 },
    { "status": "active", "label": "Active", "count": 57 },
    { "status": "rejected", "label": "Rejected", "count": 36 },
    { "status": "closed", "label": "Closed", "count": 17 }
  ]
}

Get Lifecycle Funnel

Returns lifecycle funnel showing where users drop before becoming active accounts.

GET/api/v1/lifecycle/funnel
bash
curl -X GET "https://api.spiderinfra.com/api/v1/lifecycle/funnel" \
  -H "x-api-key: YOUR_API_KEY"
json
{
  "source_system": "alpaca",
  "stages": [
    { "key": "accounts_created", "label": "Accounts created", "count": 298 },
    { "key": "onboarding", "label": "Onboarding", "count": 181 },
    { "key": "approval_pending", "label": "Approval pending", "count": 6 },
    { "key": "action_required", "label": "Action required", "count": 1 },
    { "key": "active", "label": "Active", "count": 57 }
  ],
  "transitions": [
    {
      "from_stage": "Accounts created",
      "to_stage": "Onboarding",
      "drop": 117,
      "drop_rate": 39.26
    },
    {
      "from_stage": "Onboarding",
      "to_stage": "Approval pending",
      "drop": 175,
      "drop_rate": 96.69
    }
  ]
}

Lifecycle intelligence reveals where users are stuck before they become revenue.

Growth Intelligence

Production

Behavioral telemetry meets brokerage lifecycle data.

Growth Intelligence combines behavioral telemetry with brokerage lifecycle data to identify where users are dropping off, where intent is strongest, and where commercial teams should intervene.

Telemetry can be ingested from providers such as PostHog and is isolated by Spider tenant. Growth endpoints return aggregated intelligence for the authenticated tenant only.

ℹ
Growth Intelligence currently supports PostHog as the first behavioral telemetry connector. Additional telemetry providers can map into the same canonical Spider event model.

Growth Intelligence endpoints operate on tenant-scoped normalized telemetry. PostHog is currently the default production telemetry source.

Default query parameter

source=posthog

Example

?source=posthog

Where supported, the same APIs can operate against another normalized Spider telemetry source without changing the Growth Intelligence response model.

Architecture

Behavioral Events↓Normalized Telemetry↓
Growth SummaryFunnelSegmentsRecommendationsTelemetry Health
↓Brokerage Enrichment↓Recovery / Growth Actions

Behavioral intelligence becomes financial intelligence when Spider joins telemetry identity to brokerage account state.

Authentication

All tenant-facing Growth Intelligence endpoints require the tenant Spider API key.

X-API-Key: YOUR_SPIDER_API_KEY
bash
curl \
  -H "X-API-Key: YOUR_SPIDER_API_KEY" \
  https://api.spiderinfra.com/api/v1/growth/summary
ℹ
API keys are tenant-scoped. Spider returns only data belonging to the authenticated tenant.

Errors

All Growth Intelligence endpoints are tenant authenticated. Requests without a valid tenant API key are rejected.

401 Unauthorized
json
{
  "detail": "Invalid or missing API key"
}

Growth summary

Returns a tenant-scoped summary of behavioral telemetry currently available to Spider.

The endpoint is designed to provide the headline metrics used by Growth Intelligence, including user activity, KYC engagement, funding intent, event coverage, telemetry freshness and brokerage-account identity matching.

GET/api/v1/growth/summary
ParameterTypeRequiredDescription
sourcestringOptionalTelemetry source used for the summary. Currently `posthog` is the production behavioral source. Default: posthog.

Example request

bash
curl \
  -H "X-API-Key: YOUR_SPIDER_API_KEY" \
  "https://api.spiderinfra.com/api/v1/growth/summary?source=posthog"

200 Response

json
{
  "source": "posthog",
  "events_received": 1842,
  "unique_users": 326,
  "kyc_users": 112,
  "funding_intent_users": 47,
  "users_with_account_match": 298,
  "account_match_rate": 91.41,
  "required_events_seen": 12,
  "required_events_total": 15,
  "event_coverage_rate": 80.0,
  "last_event_received_at": "2026-09-02T06:41:19.184Z",
  "last_event_occurred_at": "2026-09-02T06:41:17.921Z"
}

Field reference

FieldDescription
sourceTelemetry provider used for the calculation.
events_receivedTotal telemetry events received for the authenticated tenant and selected source.
unique_usersDistinct users represented in the telemetry dataset.
kyc_usersDistinct users who have generated at least one KYC-related behavioral event.
funding_intent_usersDistinct users showing funding intent through supported funding-related events.
users_with_account_matchNumber of telemetry users that Spider can currently associate with a brokerage account.
account_match_ratePercentage of telemetry users successfully matched to brokerage-account identity.
required_events_seenNumber of Spider's supported canonical events observed for this tenant.
required_events_totalTotal number of behavioral events Spider currently expects for full KYC and funding telemetry coverage.
event_coverage_ratePercentage of required event types observed.
last_event_received_atTimestamp when Spider most recently ingested an event from the telemetry source.
last_event_occurred_atTimestamp of the most recent behavioral event itself.
ℹ
Account match rate may be below 100% when users generate behavioral events before a brokerage account has been created, or when the telemetry source has not supplied a brokerage account identifier.

Empty / early integration

Behavioral funnel

Production

Returns tenant-scoped KYC and funding funnels calculated from behavioral telemetry.

Spider counts unique users progressing through the declared event sequence. Repeated events from the same user do not inflate funnel counts.

GET/api/v1/growth/funnel
ParameterTypeRequiredDescription
sourcestringOptionalNormalized telemetry source used to calculate the funnel. Default: posthog.

Example request

bash
curl \
  -H "X-API-Key: YOUR_SPIDER_API_KEY" \
  "https://api.spiderinfra.com/api/v1/growth/funnel?source=posthog"

200 Response

Illustrative
json
{
  "source": "posthog",
  "kyc": {
    "stages": [
      {
        "event": "session_started",
        "label": "Session started",
        "users": 326,
        "conversion_from_previous": 100.0,
        "dropoff_from_previous": 0.0
      },
      {
        "event": "kyc_started",
        "label": "KYC started",
        "users": 181,
        "conversion_from_previous": 55.5,
        "dropoff_from_previous": 44.5
      },
      {
        "event": "open_account_clicked",
        "label": "Application submitted",
        "users": 122,
        "conversion_from_previous": 67.4,
        "dropoff_from_previous": 32.6
      },
      {
        "event": "kyc_submitted",
        "label": "Brokerage account created",
        "users": 104,
        "conversion_from_previous": 85.2,
        "dropoff_from_previous": 14.8
      },
      {
        "event": "kyc_document_uploaded",
        "label": "Documents uploaded",
        "users": 93,
        "conversion_from_previous": 89.4,
        "dropoff_from_previous": 10.6
      },
      {
        "event": "kyc_approved",
        "label": "KYC approved",
        "users": 57,
        "conversion_from_previous": 61.3,
        "dropoff_from_previous": 38.7
      }
    ]
  },
  "funding": {
    "stages": [
      {
        "event": "kyc_approved",
        "label": "KYC approved",
        "users": 57,
        "conversion_from_previous": 100.0,
        "dropoff_from_previous": 0.0
      },
      {
        "event": "wallet_viewed",
        "label": "Wallet viewed",
        "users": 42,
        "conversion_from_previous": 73.7,
        "dropoff_from_previous": 26.3
      },
      {
        "event": "fund_account_clicked",
        "label": "Funding started",
        "users": 31,
        "conversion_from_previous": 73.8,
        "dropoff_from_previous": 26.2
      },
      {
        "event": "deposit_instructions_viewed",
        "label": "Deposit instructions viewed",
        "users": 24,
        "conversion_from_previous": 77.4,
        "dropoff_from_previous": 22.6
      },
      {
        "event": "bank_details_copied",
        "label": "Bank details copied",
        "users": 18,
        "conversion_from_previous": 75.0,
        "dropoff_from_previous": 25.0
      }
    ]
  },
  "generated_at": "2026-09-02T08:42:13.182Z"
}

Field reference

FieldDescription
sourceTelemetry source used for calculation.
kycSequential KYC journey.
fundingSequential funding-intent journey.
stagesOrdered funnel stages.
eventCanonical Spider behavioral event.
labelHuman-readable stage name.
usersNumber of unique users reaching the stage in sequence.
conversion_from_previousPercentage of users from the preceding stage that reached this stage.
dropoff_from_previousPercentage of users from the preceding stage that did not reach this stage.
generated_atTimestamp when the aggregate was generated.
ℹ
Funnel progression is sequential. A user is counted at a later stage only when the required preceding stages were observed in order.
Growth Funnel is behavioral telemetry. Brokerage funding and trading outcomes should be evaluated using the brokerage-enriched data layer rather than inferred solely from client-side events.

Behavior ≠ financial outcome

Spider distinguishes what a user did from what subsequently happened in the brokerage account.

Telemetry can establish intent — for example viewing deposit instructions or copying bank details. Brokerage data establishes the commercial outcome — for example whether the account was funded, traded or remained inactive.

This separation prevents behavioral signals from being presented as confirmed revenue outcomes.

Growth segments

Production

Identifies tenant-scoped behavioral cohorts where Spider detects friction, unfinished journeys or strong commercial intent.

Segments turn individual telemetry events into actionable groups. They are designed to help growth, operations and support teams decide where intervention may have the highest value.

GET/api/v1/growth/segments
ParameterTypeRequiredDescription
sourcestringOptionalNormalized telemetry source used to calculate segments. Default: posthog.

Example request

bash
curl \
  -H "X-API-Key: YOUR_SPIDER_API_KEY" \
  "https://api.spiderinfra.com/api/v1/growth/segments?source=posthog"

200 Response

Illustrative
json
{
  "source": "posthog",
  "items": [
    {
      "key": "instructions_no_bank_copy",
      "title": "Viewed deposit instructions but did not copy bank details",
      "users": 12,
      "matched_accounts": 8,
      "account_match_rate": 66.7,
      "intent": "High intent",
      "signal": "Deposit instructions viewed with no later bank-details copy",
      "action": "Send deposit support with a clear bank-transfer next step",
      "channel": "Push + Email",
      "status": "Ready",
      "requires_brokerage_enrichment": false
    },
    {
      "key": "bank_details_copied_high_intent",
      "title": "Copied bank details — verify brokerage funding outcome",
      "users": 7,
      "matched_accounts": 5,
      "account_match_rate": 71.4,
      "intent": "Very high intent",
      "signal": "Bank details copied, indicating strong external-transfer intent",
      "action": "Match the brokerage account and prioritise follow-up if it remains unfunded",
      "channel": "Advisor + Email",
      "status": "Enrich",
      "requires_brokerage_enrichment": true
    }
  ],
  "count": 2,
  "generated_at": "2026-09-02T08:43:41.144Z"
}

Segment field reference

FieldDescription
keyStable machine-readable segment identifier.
titleHuman-readable description of the cohort.
usersUnique users currently matching the behavioral definition.
matched_accountsUsers in the cohort for whom Spider has a brokerage account identifier.
account_match_ratePercentage of users in the segment with brokerage identity available.
intentBehavioral intent classification.
signalObserved behavioral pattern responsible for the classification.
actionRecommended intervention associated with the signal.
channelSuggested communication or operational channel.
statusOperational readiness of the segment.
requires_brokerage_enrichmentIndicates whether brokerage data must be joined before Spider can make the associated financial-state conclusion.
generated_atTimestamp when the segments were generated.

Current segment definitions

SegmentSignalIntentEnrichment
kyc_started_no_applicationKYC started without later application submissionMediumNo
kyc_action_required_unresolvedKYC action required without later approvalHighNo
funding_started_no_instructionsFunding clicked without later deposit-instructions viewHighNo
instructions_no_bank_copyDeposit instructions viewed without later bank-details copyHighNo
bank_details_copied_high_intentBank details copiedVery HighYes
funding_help_requestedFunding help or support requestedVery HighNo
wallet_repeat_visitsThree or more wallet visits without later funding CTAMediumNo
ℹ
Spider deliberately separates behavioral intent from financial outcome. For example, copying bank details signals strong transfer intent, but Spider does not label the account unfunded until brokerage data confirms that state.

Growth recommendations

Production

Returns next-best-action recommendations derived from currently active behavioral segments.

Only segments containing users generate recommendations.

GET/api/v1/growth/recommendations
ParameterTypeRequiredDescription
sourcestringOptionalNormalized telemetry source used to derive recommendations. Default: posthog.

Example request

bash
curl \
  -H "X-API-Key: YOUR_SPIDER_API_KEY" \
  "https://api.spiderinfra.com/api/v1/growth/recommendations?source=posthog"

200 Response

Illustrative
json
{
  "source": "posthog",
  "items": [
    {
      "key": "recommend_bank_details_copied_high_intent",
      "segment_key": "bank_details_copied_high_intent",
      "priority": "High",
      "title": "Verify and act on users who copied bank details",
      "detail": "These users showed strong transfer intent. Brokerage enrichment determines which accounts still require funding follow-up.",
      "affected_users": 7,
      "matched_accounts": 5,
      "impact": "7 users",
      "channel": "Advisor + Email",
      "requires_brokerage_enrichment": true
    },
    {
      "key": "recommend_funding_help_requested",
      "segment_key": "funding_help_requested",
      "priority": "High",
      "title": "Prioritise users actively asking for funding help",
      "detail": "A direct help or support signal is stronger than a generic engagement signal and should receive human follow-up.",
      "affected_users": 4,
      "matched_accounts": 3,
      "impact": "4 users",
      "channel": "Support + Advisor",
      "requires_brokerage_enrichment": false
    }
  ],
  "count": 2,
  "generated_at": "2026-09-02T08:45:12.981Z"
}

Field reference

FieldDescription
keyStable recommendation identifier.
segment_keyBehavioral segment responsible for the recommendation.
priorityOperational priority assigned by Spider.
titleShort recommended action.
detailExplanation of why the recommendation exists.
affected_usersNumber of users represented by the underlying segment.
matched_accountsNumber of affected users matched to brokerage accounts.
impactHuman-readable affected-user indicator.
channelRecommended execution channel.
requires_brokerage_enrichmentWhether the recommended action requires brokerage state before execution.
generated_atTimestamp when recommendations were generated.
ℹ
Recommendations are deterministic outputs from observed behavioral cohorts. Spider does not fabricate brokerage outcomes from telemetry.

Telemetry health

ProductionInfrastructure

Returns the health and data-readiness state of a tenant's telemetry integration.

The endpoint combines integration connectivity, event coverage, identity matching and telemetry freshness into one operational response.

GET/api/v1/growth/telemetry-health
ParameterTypeRequiredDescription
sourcestringOptionalTelemetry provider being evaluated. Default: posthog.

Example request

bash
curl \
  -H "X-API-Key: YOUR_SPIDER_API_KEY" \
  "https://api.spiderinfra.com/api/v1/growth/telemetry-health?source=posthog"

200 Response

Illustrative
json
{
  "provider": "posthog",
  "connection_status": "connected",
  "configured": true,
  "events_received": 1842,
  "unique_users": 326,
  "required_events_seen": 12,
  "required_events_total": 15,
  "event_coverage_rate": 80.0,
  "missing_events": [
    "kyc_rejected",
    "funding_help_clicked",
    "support_contacted"
  ],
  "users_with_account_match": 298,
  "account_match_rate": 91.4,
  "last_event_received_at": "2026-09-02T08:46:02.182Z",
  "last_event_occurred_at": "2026-09-02T08:46:01.794Z",
  "generated_at": "2026-09-02T08:46:04.208Z"
}

Field reference

FieldDescription
providerTelemetry provider being evaluated.
connection_statusCurrent integration state.
configuredWhether a provider configuration exists.
events_receivedNumber of normalized telemetry events stored.
unique_usersDistinct telemetry identities observed.
required_events_seenNumber of Spider canonical events observed.
required_events_totalTotal number of canonical behavioral events expected for complete current coverage.
event_coverage_ratePercentage of required event types observed.
missing_eventsCanonical event types Spider has not yet received.
users_with_account_matchTelemetry users associated with brokerage accounts.
account_match_ratePercentage of telemetry identities with brokerage-account association.
last_event_received_atMost recent Spider ingestion timestamp.
last_event_occurred_atMost recent underlying behavioral event timestamp.
generated_atTimestamp when health was calculated.

Connection status

not_configuredNo PostHog configuration exists.
awaiting_testConfiguration exists but no valid webhook has completed the connection.
connectedSpider has received and authenticated valid telemetry.
errorThe integration is in an error state.

Recovery Actions

New

Trigger and track revenue recovery actions. Spider closes the loop — from detecting a leak to sending the right message to the right account.

Send Recovery Email

Send a recovery email for a specific account and leak type.

POST/api/v1/actions/email/send
ParameterTypeRequiredDescription
external_account_idstringRequiredThe account to send the recovery email to.
leak_typestringRequiredThe leak type: active_not_funded, funded_no_trade, inactive_trader, idle_cash_no_position.
bash
curl -X POST "https://api.spider.ai/api/v1/actions/email/send" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_account_id": "8e0006bc-9173-458c-a09e-4e70101e5e4f",
    "leak_type": "active_not_funded"
  }'
json
{
  "id": "act_01HXYZ8ABCDEF",
  "status": "sent",
  "provider": "resend",
  "provider_message_id": "re_abc123",
  "sent_at": "2026-04-26T10:00:00Z"
}

Preview Recovery Email

Preview the email content before sending.

POST/api/v1/actions/email/preview
bash
curl -X POST "https://api.spider.ai/api/v1/actions/email/preview" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_account_id": "8e0006bc-9173-458c-a09e-4e70101e5e4f",
    "leak_type": "inactive_trader"
  }'
json
{
  "subject": "We noticed you haven't traded recently",
  "preview_text": "Your portfolio is ready when you are.",
  "html": "<html>...</html>"
}

Account Action History

Retrieve all recovery actions taken for a specific account.

GET/api/v1/actions/account/{external_account_id}
bash
curl -X GET "https://api.spider.ai/api/v1/actions/account/8e0006bc-9173-458c-a09e-4e70101e5e4f" \
  -H "X-API-Key: sk_live_xxx"
json
{
  "external_account_id": "8e0006bc-9173-458c-a09e-4e70101e5e4f",
  "actions": [
    {
      "id": "act_01HXYZ8ABCDEF",
      "leak_type": "inactive_trader",
      "channel": "email",
      "status": "clicked",
      "provider": "resend",
      "provider_message_id": "re_abc123",
      "sent_at": "2026-04-26T10:00:00Z",
      "delivered_at": "2026-04-26T10:00:05Z",
      "clicked_at": "2026-04-26T10:14:22Z"
    }
  ]
}

Bulk Send Recovery Emails

Send recovery emails to multiple accounts in a single request.

POST/api/v1/actions/email/bulk-send
bash
curl -X POST "https://api.spider.ai/api/v1/actions/email/bulk-send" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_account_ids": ["id1", "id2", "id3"],
    "leak_type": "active_not_funded"
  }'
json
{
  "total": 3,
  "sent": 3,
  "failed": 0,
  "actions": [
    { "external_account_id": "id1", "status": "sent" },
    { "external_account_id": "id2", "status": "sent" },
    { "external_account_id": "id3", "status": "sent" }
  ]
}

Track Click Events

Records a user click on a recovery email CTA.

GET/api/v1/track/click/{action_id}
ℹ
This endpoint is called automatically by Spider-generated email links. You do not need to call it manually.
json
{
  "action_id": "act_01HXYZ8ABCDEF",
  "status": "clicked",
  "clicked_at": "2026-04-26T10:14:22Z",
  "redirect_url": "https://yourbrokerage.com/fund"
}

Webhooks (Resend)

Receives email delivery, open, and click events from Resend.

POST/api/v1/webhooks/resend
ℹ
Register https://api.spider.ai/api/v1/webhooks/resend as a webhook endpoint in your Resend project settings.
json
{
  "type": "email.clicked",
  "data": {
    "email_id": "re_abc123",
    "click": {
      "link": "https://yourbrokerage.com/fund",
      "timestamp": "2026-04-26T10:14:22.000Z"
    }
  }
}

Recovery Engine

V1

From leak detection to measurable revenue recovery.

Spider's Recovery Engine connects detected revenue leaks to automated actions and tracks outcomes end-to-end. V1 supports manual recovery triggering for active_not_funded accounts via email.

Recovery flow

Detect Leak→Trigger Recovery→Send Email→Track Click→Funded→AUM Added

Trigger Recovery

Triggers Recovery Engine V1 for a supported leak type. Use dry_run=true to preview candidates without sending. Set dry_run=false to execute and send recovery emails.

POST/api/v1/recovery/trigger
ParameterTypeRequiredDescription
leak_typestringRequiredThe leak type to target. V1 supports: active_not_funded.
limitintegerOptionalMax accounts to target. Default: 10.
dry_runbooleanOptionalIf true, previews candidates without sending emails. Default: true.
force_resendbooleanOptionalIf false, skips accounts already contacted. Default: false.
⚠
Use dry_run=true first to preview candidates. Set force_resend=false to prevent duplicate sends to already-contacted users.

Request

bash
curl -X POST "https://api.spiderinfra.com/api/v1/recovery/trigger" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leak_type": "active_not_funded",
    "limit": 5,
    "dry_run": true,
    "force_resend": false
  }'

Response

json
{
  "leak_type": "active_not_funded",
  "dry_run": true,
  "candidates": 3,
  "sent": 0,
  "skipped": 3,
  "failed": 0,
  "items": [
    {
      "external_account_id": "51af5075-d4dd-4e7f-99b6-b71cc7b538d8",
      "status": "dry_run",
      "action_id": null,
      "email": "user@example.com",
      "error": null
    }
  ]
}

Get Recovery Summary

Returns recovery performance for a leak type — triggered actions, emails sent, CTR, funded users, AUM added, and estimated revenue recovered.

GET/api/v1/recovery/summary
ParameterTypeRequiredDescription
leak_typestringRequiredThe leak type to summarise (e.g. active_not_funded). Passed as a query parameter.

Metric definitions

triggered— Total recovery actions created
triggered_accounts— Unique accounts targeted
emails_sent— Recovery emails successfully sent
clicked— Tracked CTA clicks in emails
ctr— Clicked ÷ emails sent (%)
funded— Targeted users who later funded
conversion— Funded ÷ unique targeted accounts (%)
aum_added— Portfolio value added by converted users
estimated_revenue_recovered— Estimated platform revenue from recovered AUM

Request

bash
curl -X GET "https://api.spiderinfra.com/api/v1/recovery/summary?leak_type=active_not_funded" \
  -H "x-api-key: YOUR_API_KEY"

Response

json
{
  "leak_type": "active_not_funded",
  "triggered": 13,
  "triggered_accounts": 5,
  "emails_sent": 12,
  "clicked": 4,
  "ctr": 33.33,
  "funded": 1,
  "conversion": 20.0,
  "aum_added": 203.05,
  "estimated_revenue_recovered": 2.03
}

Recovery Engine connects leak detection to measurable outcomes.

Automation Engine

Coming Soon

Automatically trigger recovery actions based on lifecycle rules.

Interested in early access? Reach out to get notified when the automation engine launches.

PostHog Integration

Production

Spider receives approved behavioral events from PostHog using a tenant-specific webhook connection.

The integration is configured once per tenant. Spider authenticates incoming requests, validates the PostHog project, stores approved events, deduplicates events using the PostHog event UUID and updates integration health automatically.

Client application→PostHog→Spider webhook→Tenant telemetry store→Growth Intelligence

Configure PostHog

Creates or updates the PostHog configuration for the authenticated Spider tenant.

POST/api/v1/integrations/posthog/connect
ParameterTypeRequiredDescription
connection_namestringRequiredHuman-readable name for the integration.
deploymentstringRequiredPostHog deployment region or environment.
hoststringRequiredPostHog instance URL.
project_idstringRequiredPostHog project identifier used to validate inbound events.
bash
curl -X POST \
  https://api.spiderinfra.com/api/v1/integrations/posthog/connect \
  -H "X-API-Key: YOUR_SPIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_name": "Production PostHog",
    "deployment": "us",
    "host": "https://us.posthog.com",
    "project_id": "12345"
  }'
ℹ
Creating the configuration does not immediately mark PostHog as connected. Spider initially reports awaiting_test until a valid webhook request is received.

PostHog connection status

Returns the current PostHog integration state for the authenticated tenant.

GET/api/v1/integrations/posthog/status
bash
curl \
  -H "X-API-Key: YOUR_SPIDER_API_KEY" \
  https://api.spiderinfra.com/api/v1/integrations/posthog/status

Connection states

not_configuredNo PostHog configuration exists for this tenant.
awaiting_testConfiguration exists but Spider has not yet received and validated a PostHog webhook.
connectedSpider has successfully authenticated a PostHog webhook for the tenant.
errorSpider encountered a configuration or validation problem.

Example response — connected

json
{
  "connection_status": "connected",
  "webhook_configured": true,
  "last_event_received_at": "2026-09-02T06:41:19.184Z"
}

PostHog webhook handshake

Inbound integration endpointNot called using the customer's Spider API key

Spider generates a tenant-specific webhook URL and authorization secret. These are configured as a PostHog webhook destination.

When PostHog sends the first valid request, Spider validates the authorization secret and project ID and changes the integration state from awaiting_test to connected.

Webhook URL

bash
https://api.spiderinfra.com/api/v1/integrations/posthog/webhook/{integration_id}

Headers

bash
Authorization: Bearer YOUR_SPIDER_POSTHOG_WEBHOOK_SECRET
Content-Type: application/json

Example payload

json
{
  "project_id": "12345",
  "event_id": "01a05b55-80fa-7e61-a610-3d16e7d6c1d3",
  "event_name": "bank_details_copied",
  "occurred_at": "2026-09-02T06:41:17.921Z",
  "distinct_id": "client-user-id",
  "properties": {
    "tenant_id": "example-tenant",
    "user_id": "client-user-id",
    "account_id": "brokerage-account-id",
    "source": "mobile"
  }
}
⚠
Never expose the PostHog webhook authorization secret in frontend application code or public documentation. The value shown here is illustrative only.

Supported behavioral events

Canonical events currently supported by Spider's behavioral telemetry model.

Account / Session

Identifies application engagement and session activity.

session_started

KYC

Measures progression, abandonment and friction across account opening and verification.

kyc_startedkyc_step_completedopen_account_clickedkyc_submittedkyc_document_uploadedkyc_approvedkyc_rejectedkyc_action_required

Funding / Activation

Identifies funding intent and where approved users stall before depositing capital.

wallet_viewedfund_account_clickeddeposit_instructions_viewedbank_details_copiedfunding_help_clickedsupport_contacted
ℹ
Client event names can later be mapped into Spider's canonical event model, allowing enterprise clients to retain their existing telemetry naming conventions.

Identity resolution

Behavioral activity can occur before a brokerage account exists. Spider therefore preserves the client user identity throughout the journey and associates it with the brokerage account once an account identifier becomes available.

Telemetry distinct ID / client user ID→Brokerage account ID→Spider account record
json
{
  "distinct_id": "auth0|example-user",
  "properties": {
    "user_id": "auth0|example-user",
    "account_id": "broker-account-uuid"
  }
}
ℹ
account_id may legitimately be null for pre-account events such as early KYC activity.

Event delivery and deduplication

Webhook systems may retry delivery. Spider stores the original PostHog event UUID as source_event_id and deduplicates repeated deliveries so the same event does not inflate Growth Intelligence metrics.

Recommended telemetry payload

Spider needs behavioral and lifecycle metadata, not sensitive KYC documents.

Recommended

  • ✓event name
  • ✓event UUID
  • ✓timestamp
  • ✓stable user identifier
  • ✓brokerage account identifier when available
  • ✓platform
  • ✓application version
  • ✓workflow metadata relevant to the event

Avoid sending

  • ✕document images
  • ✕passport numbers
  • ✕bank credentials
  • ✕unnecessary customer PII
  • ✕full KYC document payloads

Sync Runs

List tracked sync runs for the current tenant.

GET/api/v1/sync-runs
json
[
  {
    "id": 19,
    "tenant_id": "quantl-tenant",
    "source_system": "alpaca",
    "sync_type": "backfill",
    "status": "completed",
    "records_processed": 0,
    "records_failed": 0,
    "error_message": null,
    "started_at": "2026-04-12T12:20:46.735513Z",
    "completed_at": "2026-04-12T12:20:46.741571Z"
  }
]

Trigger Backfill

Create and auto-complete a tracked backfill sync run for operational validation.

POST/api/v1/sync-runs/backfill
bash
curl -X POST "https://api.spider.ai/api/v1/sync-runs/backfill?source_system=alpaca" \
  -H "X-API-Key: your_api_key_here"
json
{
  "id": 19,
  "tenant_id": "quantl-tenant",
  "source_system": "alpaca",
  "sync_type": "backfill",
  "status": "completed",
  "records_processed": 0,
  "records_failed": 0,
  "error_message": null,
  "started_at": "2026-04-12T12:20:46.735513Z",
  "completed_at": "2026-04-12T12:20:46.741571Z"
}

Event-based Leaks

Legacy

Retrieve revenue leaks detected from the legacy event stream.

⚠
This endpoint reflects data from the legacy /events pipeline. For richer, more accurate leak data, use the Leak Intelligence endpoints.
GET/api/v1/leaks
json
{
  "leaks": [
    {
      "type": "dormant_account",
      "users": 42,
      "estimated_revenue_loss": 12500,
      "detected_at": "2026-03-24T08:00:00Z"
    },
    {
      "type": "unfunded_account",
      "users": 18,
      "estimated_revenue_loss": 4200,
      "detected_at": "2026-03-24T08:00:00Z"
    }
  ]
}

Start detecting revenue leaks today

No dashboards to configure. Real-time from the first event.

Get API Key