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://api.bird.com/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":"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

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

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

Request Headers

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

curl 'https://api.bird.com/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

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

---

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.