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

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`` - Filters for journeys with non-null IDs

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

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.

Last updated

Was this helpful?