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:

Przykład kodu

Authorization: Bearer <YOUR_TOKEN>

Base URLs

Metrics API: https://api.bird.com/workspaces/{workspaceId}/datahub/explorer/run-query
Journeys API: https://api.bird.com/workspaces/{workspaceId}/journeys

Retrieve Journey Metrics

Get detailed performance metrics for your journeys within a specified time range.

Endpoint

Przykład kodu

POST https://api.bird.com/workspaces/{workspaceId}/datahub/explorer/run-query?format=json

Request Headers

Przykład kodu

Accept: application/json
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

Request Body

Przykład kodu

{"queryDefinition":"group_by: journeyID journeyName aggregate: sentCount, deliveredCount, globalHoldoutsCount, journeyHoldoutsCount, bouncedCount, openCount, clickCount, spamComplaintCount, unsubscribedCount where: journeyID ~ f`-null` limit: 100","modelName":"marketing.messaging_metrics","parameters":{"startDateFilter":"2025-08-08 00:00:00","endDateFilter":"2025-11-06 23:59:59"}}

Parameters

Parameter	Type	Required	Description
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' - Filter for metrics with non-null journey IDs
- Multiple filters: where: journeyID ~ f'-null' where: journey.status = 1
- Only filter strings (~ f'-null') and equality predicates (field = value) can be used.
Grouping: group_by: journeyID - Groups results by journey ID
Aggregations: Comma-separated list of metrics to retrieve

Available Metrics

Metric	Description
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

Przykład kodu

{
  "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 objects
result.schema: Schema definition describing the returned fields
Each data object contains the requested metrics for a specific journey

List Journeys

Retrieve a list of journeys with their configuration details.

Endpoint

Przykład kodu

GET https://api.bird.com/workspaces/{workspaceId}/journeys

Request Headers

Przykład kodu

Accept: application/json
Authorization: Bearer <YOUR_TOKEN>

Query Parameters

Parameter	Type	Required	Default	Description
limit	integer	No	10	Number of journeys to return (max 99)
status	string	No	all	Filter by journey status (active, inactive, draft)

Example Request

Przykład kodu

curl 'https://api.bird.com/workspaces/{workspaceId}/journeys?limit=50&status=active' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Response

Przykład kodu

{
  "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

Field	Description
results	Array of journey objects
total	Total number of journeys matching the criteria
nextPageToken	Token for pagination (if more results available)

Journey Object Fields

Field	Description
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

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.