Journey Metrics
Journey Metrics API Documentation
This API allows you to retrieve metrics for your marketing journeys.
Authentication
All API requests require authentication using a Bearer token in the Authorization header:
Authorization: Bearer <YOUR_TOKEN>
Base URLs
Metrics API:
https://api.bird.com/workspaces/{workspaceId}/datahub/explorer/run-query
Journeys API:
https://app.bird.com/api/workspaces/{workspaceId}/journeys
Retrieve Journey Metrics
Get detailed performance metrics for your journeys within a specified time range.
Endpoint
POST https://api.bird.com/workspaces/{workspaceId}/datahub/explorer/run-query?format=json
Request Headers
Accept: application/json
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>
Request Body
{
"queryDefinition": "where: journeyID ~ f`-null`, group_by: journeyID, journeyName aggregate: sentCount, deliveredCount, globalHoldoutsCount, journeyHoldoutsCount, bouncedCount, openCount, clickCount, spamComplaintCount, unsubscribedCount",
"modelName": "marketing.messaging_metrics",
"parameters": {
"startDateFilter": "2025-09-21 00:00:00",
"endDateFilter": "2025-09-22 23:59:59"
}
}
Parameters
queryDefinition
string
Yes
Query string defining filters, grouping, and aggregations
modelName
string
Yes
Data model to query (use marketing.messaging_metrics
)
parameters.startDateFilter
string
Yes
Start date and time in format YYYY-MM-DD HH:MM:SS
parameters.endDateFilter
string
Yes
End date and time in format YYYY-MM-DD HH:MM:SS
Query Definition Components
Filter:
where: journeyID ~ f\
-null`` - Filters for journeys with non-null IDsGrouping:
group_by: journeyID
- Groups results by journey IDAggregations: Comma-separated list of metrics to retrieve
Available Metrics
sentCount
Total number of messages sent
deliveredCount
Number of successfully delivered messages
globalHoldoutsCount
Messages skipped by global hold-out
journeyHoldoutsCount
Messages skipped by journey-specific hold-out
bouncedCount
Number of bounced messages
openCount
Number of message opens including bot opens
clickCount
Number of link clicks including bot clicks
spamComplaintCount
Number of spam complaints
unsubscribedCount
Number of unsubscribe events
Response
{
"result": {
"data": [
{
"journeyID": "12345678-1234-5678-9abc-123456789012",
"sentCount": 46572,
"deliveredCount": 36926,
"globalHoldoutsCount": 4346,
"journeyHoldoutsCount": 0,
"bouncedCount": 346,
"openCount": 10918,
"clickCount": 72,
"spamComplaintCount": 4,
"unsubscribedCount": 40
}
],
"schema": {
"fields": [
...
]
}
}
}
Response Fields
result.data
: Array of journey metrics objectsresult.schema
: Schema definition describing the returned fieldsEach data object contains the requested metrics for a specific journey
List Journeys
Retrieve a list of journeys with their configuration details.
Endpoint
GET https://app.bird.com/api/workspaces/{workspaceId}/journeys
Request Headers
Accept: application/json
Authorization: Bearer <YOUR_TOKEN>
Query Parameters
limit
integer
No
10
Number of journeys to return (max 99)
status
string
No
all
Filter by journey status (active
, inactive
, draft
)
Example Request
curl 'https://app.bird.com/api/workspaces/{workspaceId}/journeys?limit=50&status=active' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'
Response
{
"results": [
{
"id": "12345678-1234-5678-9abc-123456789012",
"name": "Welcome Series",
"status": "active",
"description": "",
"publisherId": "abcdef12-3456-7890-abcd-ef1234567890",
"createdAt": "2025-01-17T06:10:00.041Z",
"updatedAt": "2025-02-19T11:45:26.179Z",
"publishedVersion": "87654321-4321-8765-dcba-210987654321",
"publishedVersionStepCount": 25,
"invocationCount": 0,
"conversionCount": 0,
"stepFeatures": ["sms"],
"tags": ["tag12345-6789-0123-4567-890123456789"],
"trigger": {
"type": "journey-engagement",
"data": {
"allowReentry": false,
"audienceId": "audience1-2345-6789-0123-456789012345",
"endOnExit": false,
"event": "entered"
}
}
}
],
"total": 1,
"nextPageToken": "eyJsYXN0SWQiOiIxMjM0NTY3OCIsInRpbWVzdGFtcCI6MTY0MDk5ODgwMH0="
}
Response Fields
results
Array of journey objects
total
Total number of journeys matching the criteria
nextPageToken
Token for pagination (if more results available)
Journey Object Fields
id
Unique journey identifier
name
Journey name
status
Current status (active
, inactive
, draft
)
description
Journey description
createdAt
Creation timestamp (ISO 8601)
updatedAt
Last modification timestamp (ISO 8601)
publishedVersion
ID of the currently published version
publishedVersionStepCount
Number of steps in the published version
stepFeatures
Array of communication channels used (e.g., sms
, email
)
tags
Array of tag IDs associated with the journey
trigger
Trigger configuration object
Error Handling
The API returns standard HTTP status codes:
200 OK: Request successful
400 Bad Request: Invalid request parameters
401 Unauthorized: Invalid or missing authentication token
404 Not Found: Resource not found
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error
Rate Limits
API requests are subject to rate limiting. If you exceed the rate limit, you'll receive a 429 Too Many Requests
response. Implement exponential backoff in your client to handle rate limiting gracefully.
Last updated
Was this helpful?