Skip to main content
Connect your BigQuery project to export router exposure data for analysis and import your product events to define custom metrics in Portal.

​
Prerequisites

1

Create a BigQuery dataset

Create a BigQuery dataset in your GCP project to store router data. If you only plan to import events (not export), you can skip this step.
2

Create a service account

Go to the Service Accounts page in your GCP project and create a new service account for the Inworld sync job. On the permissions page, grant it the following project-level roles:
  • Service Account Token Creator (roles/iam.serviceAccountTokenCreator) — allows Inworld to impersonate this account when running sync jobs
  • BigQuery Job User (roles/bigquery.jobUser) — allows the account to run BigQuery jobs
3

Grant Inworld impersonation access

Navigate to your newly created service account and open the Principals with access tab. Click Grant access and add the following principal:
inworld-sync@inworld-ai-prod.iam.gserviceaccount.com
Assign it the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator). This allows the Inworld sync service to impersonate your service account for BigQuery operations.
4

Grant BigQuery dataset permissions

Go to BigQuery and select the dataset you want to use with Inworld. On the dataset page, go to Share → Manage Permissions and click Add principal. Enter the email of the service account you created in Step 2 and assign the appropriate role:
  • BigQuery Data Editor — required for exporting router exposure data to your dataset
  • BigQuery Data Viewer — required for importing events from your source tables
If you plan to use both export and import on the same dataset, BigQuery Data Editor is sufficient (it includes viewer permissions). Repeat this step for each dataset you plan to use.
5

Configure the integration in Portal

In Portal, go to Routers and click Set Up Metrics to open the Data Integrations page, then click Add Integration and select BigQuery. Enter the following:
FieldValue
Project IDYour GCP project ID
Dataset IDYour BigQuery dataset ID from Step 1 (used for export)
Service Account EmailThe service account email from Step 2
BigQuery LocationThe region where your dataset is located
Click Enable to save your credentials. You can then toggle export and import independently in the Data Sync section.

​
Exporting to BigQuery

Toggle Export to BigQuery on in the Data Sync section of your integration settings. When enabled, router exposure data is automatically written to your BigQuery dataset.

​
Make a request to your router

Call the Chat Completions API with your router, populating a unique user ID in the user field: 
curl --request POST \
  --url https://api.inworld.ai/v1/chat/completions \
  --header 'Authorization: Basic <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "inworld/my-router",
    "messages": [{"role": "user", "content": "Hello"}],
    "user": "<your-user-id>"
  }'
The router exposure data will include the user in the data export, so you can tie the specific request to the right user.

​
Analyze your data

The router exposure data will flow to your BigQuery dataset automatically (data syncs every ~8 hours). You will see a row for each router, route, and variant that a user was exposed to every hour. Each row will include:
  • alias_id — Your router’s ID
  • route_id — The route that the user was routed to
  • variant_id — The variant that the user was exposed to
  • user_id — The user that was exposed to this router, route, and variant
  • timestamp — The time of the most recent event in the hourly bucket in which the user was exposed to this router, route, and variant
You can use this data in conjunction with your existing metrics to understand how your metrics trend based on the router, route, or variant that the user was exposed to.

​
Importing from BigQuery

Toggle Import from BigQuery on in the Data Sync section to start pulling your product events into Portal.

​
Define events to import

In the Events to import section that appears after enabling import, click Add Event. For each event, you map columns from a BigQuery table to the fields Inworld expects:
FieldDescriptionExample
Event NameA logical name for this event in Portal.user_donation
DescriptionOptional description of when this event is triggered.Fires when a user completes a donation
DatasetThe BigQuery dataset containing the source table.user_data
Table NameThe BigQuery table to read events from.donations
Event Field NameThe column that identifies the event type.event_name
User ID Field NameThe column containing the user identifier.user_id
Timestamp Field NameThe column with the event timestamp.created_at
Event UUID Field NameThe column with a unique identifier per event row.event_uuid
Event names can only contain letters, numbers, underscores, and hyphens.
You can add multiple events, each pointing to a different table or filtering on a different event type within the same table.

​
Schema requirements

Your BigQuery source table must meet these requirements:
ColumnTypeNotes
Timestamp fieldTIMESTAMP or DATETIMEUsed to determine sync boundaries and event ordering
User ID fieldSTRINGMust match the user value passed in Chat Completions API requests for correlation with router exposures
Event UUID fieldSTRINGMust be unique per row to ensure idempotent imports
The service account configured in Prerequisites must have BigQuery Data Viewer access to the specified dataset and table.

​
How import works

  • Inworld reads from your BigQuery tables using the BigQuery Storage Read API for efficient data transfer.
  • Events are synced approximately every 8 hours. Imports are incremental — only new rows since the last sync are fetched.
  • User identity is matched using the User ID field. To correlate imported events with router exposures, ensure the same user identifier is passed as the user field in your Chat Completions API requests and in the User ID column of your BigQuery table.
  • Once events are imported, their numeric properties are automatically discovered and become available for metric configuration.

​
Next steps

Once your events are importing, create custom metrics to track how routing decisions impact your KPIs.