Insights API Documentation

The Insights API provides access to the usage database of The Wallet Crew (TWC) platform.
It enables you to query Logs, Events, and Metrics using Kusto Query Language (KQL).

This API is designed for technical users extracting data programmatically, but queries remain understandable for medium-technical users as well.

Authentication & Permissions

Access requires standard TWC authentication.

• Permission required: Insights:Read
• Authentication flow: use your existing TWC auth token (e.g., from login or service-to-service).
• Single-tenant scope: you can only query data from your own tenant.

Example header:

Authorization: Bearer <your_access_token>

Data Retention & Limits

• Logs: retained 45 days
• Events: retained indefinitely
• Metrics: retained indefinitely

Rate limit: 60 API calls per minute.
To request higher limits, open a support ticket.

API Endpoint

All queries are executed via:

POST /api/{tenantId}/insights/query

• {tenantId} = your tenant identifier
• Request body must contain a query string in KQL

Schema

The Insights database contains three tables:

Logs

Contains errors and traces related to platform activity.
Useful for debugging and monitoring health.

Events

Contains:

• Page views
• API requests
• Custom business events (full list here)

Metrics

Represents snapshots of the system state, taken hourly.

Querying Data

Example with Axios (JavaScript)

const result = await axios.post<{ rows: Array<Array<unknown>> }>(
  `/api/${tenantId}/insights/query`,
  {
    query: `
Events 
| where eventType == "Customer:Upserted" 
| summarize count()`,
  }
);

console.log(result.data.rows);

Example with Curl

curl -X POST "https://<your-host>/api/<tenantId>/insights/query" \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Events | where eventType == \"Customer:Upserted\" | summarize count()"
  }'

Common Queries (Use Cases)

1. Count new customers

Events
| where eventType == "Customer:Upserted"
| summarize NewCustomers = count()

2. Count pass installations

Events
| where eventType == "Pass:Installed"
| summarize PassInstallations = count()

3. Count requests per day

Events
| where eventType == "Request"
| summarize RequestsPerDay = count() by bin(timestamp, 1d)

4. Count redirects per day

Events
| where eventType == "Redirect:Redirected"
| summarize RedirectsPerDay = count() by bin(timestamp, 1d)

5. Count page views per browser

Events
| where eventType == "PageView"
| extend browser = tostring(properties.browser)
| summarize PageViews = count() by browser

Representative Event Types

Here are some of the most common eventType values you may want to query:

• Customer lifecycle

  • Customer:Upserted
  • Y2:Customer:Created
  • Y2:Customer:Updated

• Pass lifecycle

  • Pass:Created
  • Pass:Updated
  • Pass:Installed
  • Pass:Uninstalled

• User actions

  • action:addToAppleWallet
  • action:addToGoogleWallet
  • action:loginWithGoogle
  • action:loginWithApple

• Tracking & analytics

  • Request
  • PageView
  • Redirect:Redirected
  • step:complete
  • step:changed

Troubleshooting

• 401 Unauthorized

  • Ensure your token is valid and includes Insights:Read.

• 429 Too Many Requests

  • You exceeded the rate limit (60 calls/minute). Implement retries with exponential backoff.

• Query takes too long

  • Simplify query or reduce time window.
  • Avoid unbounded queries on large tables.

FAQ

Q: Can I export results to CSV/JSON?
Not directly via API, but you can consume JSON output and transform it locally.

Q: Can I query multiple tenants?
No, access is restricted to your tenant only.

Q: Does the Insights DB contain personal data?
No, it does not contain PII.

Q: Can I set up alerts (thresholds, triggers)?
Not at the moment.

Would you like me to also add a “Getting Started” section with a ready-to-run curl command (including placeholders for tenantId and token) so that new developers can test the API immediately?