Triplewhale api

Step 1: Generate an API key in the Triple Whale workspace

Log in to Triple Whale, navigate to Settings → Integrations → API. Click 'Generate API Key', label it for the integration you're building (e.g., 'snowflake-pipeline-prod'), and copy the key to a secret manager. The key is shown once; if you lose it, you regenerate. Treat it like a database password.

Step 2: Confirm your API base URL and rate limits

Triple Whale's API base is `https://api.triplewhale.com/api/v2` in 2026. Rate limits are documented per endpoint but the default is 60 requests per minute per key with burst tolerance. Heavy historical backfills should be paginated and throttled to avoid 429 responses.

BASE_URL = "https://api.triplewhale.com/api/v2"
# Default rate limit: 60 req/min per key
# 429 responses include Retry-After header - respect it

Step 3: Authenticate a test request

All Triple Whale API requests use Bearer token authentication with the API key generated in Step 1. Run a smoke test against the `/me` or `/workspace` endpoint to confirm the key works and returns the expected workspace ID. If authentication fails, the most common cause is a copy-paste truncation or trailing whitespace in the key.

curl -X GET "$BASE_URL/me" \
  -H "Authorization: Bearer $TRIPLEWHALE_API_KEY" \
  -H "Content-Type: application/json"

Step 4: Query the attribution endpoint for a date range

The attribution endpoint returns ad-level attribution data with per-channel deduplication. Start with a 7-day query to validate the response shape, then expand to your full historical range. The response includes spend, revenue, ROAS, attributed conversions per ad, ad set, and campaign across every connected ad platform.

curl -X GET "$BASE_URL/attribution" \
  -G \
  --data-urlencode "start_date=2026-05-13" \
  --data-urlencode "end_date=2026-05-20" \
  --data-urlencode "granularity=ad" \
  --data-urlencode "model=time_decay" \
  -H "Authorization: Bearer $TRIPLEWHALE_API_KEY"

Step 5: Paginate historical backfills

Triple Whale paginates large responses via cursor or page parameters. Historical backfills (90+ days of ad-level data) should chunk the request by week or month to stay under per-response size limits and avoid timeout-induced retries. Persist the cursor between chunks so you can resume on failure.

# Pseudocode: chunk by week for historical backfill
for week_start in date_range("2024-01-01", "2026-05-20", step="7d"):
    week_end = week_start + 7d
    response = fetch_attribution(week_start, week_end)
    store_to_warehouse(response.rows)
    persist_cursor(week_end)
    sleep(1)  # throttle to stay under rate limit

Step 6: Pull Shopify orders, products, and customers via the data endpoints

Beyond attribution, Triple Whale exposes the underlying Shopify-derived data (orders, products, customers, cohorts) via dedicated endpoints. For most warehouse-export use cases, the right pattern is to pull attribution + orders + customers + products as separate tables and join them in your warehouse - not in the API requests.

# Four parallel pulls for the data warehouse:
# /attribution  → ad-level spend + attributed revenue
# /orders       → order-level data with customer + product references
# /customers    → customer-level data with cohort + LTV
# /products     → product catalog with SKU-level metadata

Step 7: Schedule incremental refreshes

After the initial backfill, run incremental refreshes on a schedule. The recommended cadence is hourly for attribution (the underlying data updates throughout the day as the optimizer rebalances) and daily for orders / customers / products. Use the `updated_after` query parameter on each endpoint to fetch only records changed since the last successful run.

# Hourly cron, attribution incremental:
last_run = read_state("attribution_last_run")
response = fetch_attribution(
    start_date=last_run - 1d,  # 1-day overlap for late-arriving data
    end_date=now,
    updated_after=last_run,
)
upsert_to_warehouse(response.rows, key=["date", "ad_id"])
write_state("attribution_last_run", now)

Step 8: Set up monitoring and alerting on the pipeline

API integrations fail silently if you don't monitor them. At minimum, alert on: failed authentication (401), rate-limit-induced backoff exceeding 5 minutes (429), no rows returned in an expected refresh window (data gap), and per-endpoint latency exceeding 30 seconds (degraded API or oversized query). Log every request-response pair to your observability stack for diagnosis.

# Pseudocode: minimal monitoring
on_failure(
    auth_error=alert("page:on-call", "TW API auth failed"),
    rate_limit=alert("slack:#data", "TW API throttled, backing off"),
    empty_response=alert("slack:#data", f"TW API returned 0 rows for {date}"),
    high_latency=alert("slack:#data", f"TW API >30s for {endpoint}"),
)