Insights API

Use Insights API to get information about the wallet crew usage

The Insights API gives access to the usage database of The Wallet Crew (TWC) platform. 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 and 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>

Retention and rate 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.

Endpoint

All queries are executed via:

POST /api/{tenantId}/insights/query

• {tenantId} = your tenant identifier

• Request body must contain a query string in KQL

Tables and schema

The Insights database contains three tables:

Logs

Column	Type
eventId	guid
timestamp	datetime
tenantId	string
eventType	string
operationId	string
properties	dynamic

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

Events

Column	Type
eventId	guid
timestamp	datetime
tenantId	string
eventType	string
operationId	string
properties	dynamic

Contains:

• Page views

• API requests

• Custom business events

Metrics

Column	Type
metricId	guid
tenantId	string
metricType	string
value	dynamic
properties	dynamic
timestamp	datetime

Represents snapshots of the system state, taken hourly.

Run queries

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

Count new customers

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

Count pass installations

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

Count requests per day

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

Count redirects per day

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

Count page views per browser

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

Common 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

Can I export results to CSV/JSON?

Not directly via the API.

Consume the JSON response and convert it locally.

Can I query multiple tenants?

No.

Access is restricted to your tenant only.

Does the Insights DB contain personal data?

No.

It does not contain PII.

Can I set up alerts (thresholds, triggers)?

Not at the moment.