PixelFlow

Get journeys

get_journeys

Read-onlyIdempotent

Get visitor journeys on one site, one row per visitor with an event in the date range. A journey covers that visitor's events in the lookback_days up to their last event in the range. Each row has the journey's value per currency, the count of each event, its last 50 events with their times, and the first and last touch credited (source and UTM tags). Events with no visitor id are their own rows. Ranges before the plan's journey lookback are refused. Use it when the user asks about customer, user, or conversion journeys: what visitors did on the site before they converted, and which first and last touch the conversion is credited to.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "site_id": "<site_id>",
      "from": "<from>",
      "to": "<to>"
    },
    "name": "get_journeys"
  }
}

Input Schema

Name	Required	Description
`to`	Yes	Range end. YYYY-MM-DD means the end of that day in `timezone`, so the whole day is included; a full ISO 8601 timestamp is used as is.
`from`	Yes	Range start. YYYY-MM-DD means the start of that day in `timezone`; a full ISO 8601 timestamp is used as is.
`page`	No	Page to return. Default 1.
`sort`	No	most_recent: newest latest event first. highest_value: largest journey value first. Default most_recent.
`limit`	No	Journeys per page. Default 25.
`events`	No	Only journeys with at least one of these events, such as Purchase. Names are in list_supported_values's `events`. Default: the conversion events. Add PageView to include visitors who did not convert.
`site_id`	Yes	Site to act on, as returned by list_sites.
`sources`	No	Only journeys with at least one event from these traffic source buckets, such as facebook, google, organic, or direct. Names are in list_supported_values's `sources`. (not set) matches a blank value.
`timezone`	No	IANA time zone such as Europe/Berlin. Default UTC. Returned times and day buckets use it.
`utm_term`	No	Only journeys with at least one event carrying one of these UTM terms (usually the ad set). (not set) matches a blank value.
`visitor_id`	No	One visitor's journey, visitor_id from an earlier row or from list_events.
`utm_content`	No	Only journeys with at least one event carrying one of these UTM contents (usually the ad). (not set) matches a blank value.
`utm_campaign`	No	Only journeys with at least one event carrying one of these UTM campaigns. (not set) matches a blank value.

Output Schema

Name	Required	Description
`sort`	Yes	Sort used.
`total`	Yes	Journeys matching the filters, across all pages.
`window`	Yes	Exact range read, after applying timezone.
`journeys`	Yes	Journeys on this page, in the requested sort.
`timezone`	Yes	IANA time zone used for dates and times. UTC when none was passed.
`next_page`	Yes	Pass as page for the next page, with the same filters and sort. null: last page.
`lookback_days`	Yes	Days before a visitor's last event that their journey covers.

Schema Changelog

Changes observed during successful MCP inspections.

Changed18 schema fields changedNov 2, 2026

removedOutput schema / properties / journeys / items / properties / first_touch / additionalProperties
```
Removed value: -false
```

addedOutput schema / properties / journeys / items / properties / first_touch / anyOf

Added value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "source": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Source, such as facebook or organic."
+      },
+      "utm_campaign": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM campaign."
+      },
+      "utm_content": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM content (usually the ad)."
+      },
+      "utm_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM id."
+      },
+      "utm_medium": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM medium."
+      },
+      "utm_term": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM term (usually the ad set)."
+      }
+    },
+    "required": [
+      "source",
+      "utm_campaign",
+      "utm_term",
+      "utm_content",
+      "utm_medium",
+      "utm_id"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / journeys / items / properties / first_touch / properties

Removed value: -{
-  "source": {
-    "description": "Source, such as facebook or organic.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_campaign": {
-    "description": "UTM campaign.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_content": {
-    "description": "UTM content (usually the ad).",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_id": {
-    "description": "UTM id.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_medium": {
-    "description": "UTM medium.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_term": {
-    "description": "UTM term (usually the ad set).",
-    "type": [
-      "string",
-      "null"
-    ]
-  }
-}

removedOutput schema / properties / journeys / items / properties / first_touch / required

Removed value: -[
-  "source",
-  "utm_campaign",
-  "utm_term",
-  "utm_content",
-  "utm_medium",
-  "utm_id"
-]

removedOutput schema / properties / journeys / items / properties / first_touch / type
```
Removed value: -[
-  "object",
-  "null"
-]
```

addedOutput schema / properties / journeys / items / properties / id / anyOf

Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / journeys / items / properties / id / type
```
Removed value: -[
-  "integer",
-  "null"
-]
```
removedOutput schema / properties / journeys / items / properties / last_touch / additionalProperties
```
Removed value: -false
```

addedOutput schema / properties / journeys / items / properties / last_touch / anyOf

Added value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "source": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Source, such as facebook or organic."
+      },
+      "utm_campaign": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM campaign."
+      },
+      "utm_content": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM content (usually the ad)."
+      },
+      "utm_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM id."
+      },
+      "utm_medium": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM medium."
+      },
+      "utm_term": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM term (usually the ad set)."
+      }
+    },
+    "required": [
+      "source",
+      "utm_campaign",
+      "utm_term",
+      "utm_content",
+      "utm_medium",
+      "utm_id"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / journeys / items / properties / last_touch / properties

Removed value: -{
-  "source": {
-    "description": "Source, such as facebook or organic.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_campaign": {
-    "description": "UTM campaign.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_content": {
-    "description": "UTM content (usually the ad).",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_id": {
-    "description": "UTM id.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_medium": {
-    "description": "UTM medium.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_term": {
-    "description": "UTM term (usually the ad set).",
-    "type": [
-      "string",
-      "null"
-    ]
-  }
-}

removedOutput schema / properties / journeys / items / properties / last_touch / required

Removed value: -[
-  "source",
-  "utm_campaign",
-  "utm_term",
-  "utm_content",
-  "utm_medium",
-  "utm_id"
-]

removedOutput schema / properties / journeys / items / properties / last_touch / type
```
Removed value: -[
-  "object",
-  "null"
-]
```
addedOutput schema / properties / journeys / items / properties / values / items / properties / currency / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
removedOutput schema / properties / journeys / items / properties / values / items / properties / currency / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / journeys / items / properties / visitor_id / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / journeys / items / properties / visitor_id / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / next_page / anyOf

Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / next_page / type
```
Removed value: -[
-  "integer",
-  "null"
-]
```

Changed17 schema fields changedNov 2, 2026

addedInput schema / properties / events

Added value: +{
+  "description": "Only journeys with at least one of these events, such as Purchase. Names are in list_supported_values's `events`. Default: the conversion events. Add PageView to include visitors who did not convert.",
+  "items": {
+    "type": "string"
+  },
+  "maxItems": 50,
+  "type": "array"
+}

changedInput schema / properties / from / description

Previous value: -"Range start. YYYY-MM-DD is the start of that calendar day in timezone. A full ISO instant is that instant. Omit when journey_id is set"New value: +"Range start. YYYY-MM-DD means the start of that day in `timezone`; a full ISO 8601 timestamp is used as is."

removedInput schema / properties / journey_id

Removed value: -{
-  "description": "One conversion id from an earlier get_journeys result",
-  "type": "number"
-}

addedInput schema / properties / limit

Added value: +{
+  "description": "Journeys per page. Default 25.",
+  "maximum": 50,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / page

Added value: +{
+  "description": "Page to return. Default 1.",
+  "maximum": 10000,
+  "minimum": 1,
+  "type": "integer"
+}

removedInput schema / properties / site

Removed value: -{
-  "description": "Domain, id, or external id from list_sites",
-  "type": "string"
-}

addedInput schema / properties / site_id

Added value: +{
+  "description": "Site to act on, as returned by list_sites.",
+  "type": "integer"
+}

addedInput schema / properties / sort

Added value: +{
+  "description": "most_recent: newest latest event first. highest_value: largest journey value first. Default most_recent.",
+  "enum": [
+    "most_recent",
+    "highest_value"
+  ],
+  "type": "string"
+}

addedInput schema / properties / sources

Added value: +{
+  "description": "Only journeys with at least one event from these traffic source buckets, such as facebook, google, organic, or direct. Names are in list_supported_values's `sources`. (not set) matches a blank value.",
+  "items": {
+    "type": "string"
+  },
+  "maxItems": 50,
+  "type": "array"
+}

changedInput schema / properties / timezone / description

Previous value: -"IANA timezone. Omitted means UTC, and the response says UTC"New value: +"IANA time zone such as Europe/Berlin. Default UTC. Returned times and day buckets use it."

changedInput schema / properties / to / description

Previous value: -"Range end. YYYY-MM-DD is the end of that calendar day in timezone, so later events that day are included. A full ISO instant is that instant. Omit when journey_id is set"New value: +"Range end. YYYY-MM-DD means the end of that day in `timezone`, so the whole day is included; a full ISO 8601 timestamp is used as is."

addedInput schema / properties / utm_campaign

Added value: +{
+  "description": "Only journeys with at least one event carrying one of these UTM campaigns. (not set) matches a blank value.",
+  "items": {
+    "type": "string"
+  },
+  "maxItems": 50,
+  "type": "array"
+}

addedInput schema / properties / utm_content

Added value: +{
+  "description": "Only journeys with at least one event carrying one of these UTM contents (usually the ad). (not set) matches a blank value.",
+  "items": {
+    "type": "string"
+  },
+  "maxItems": 50,
+  "type": "array"
+}

addedInput schema / properties / utm_term

Added value: +{
+  "description": "Only journeys with at least one event carrying one of these UTM terms (usually the ad set). (not set) matches a blank value.",
+  "items": {
+    "type": "string"
+  },
+  "maxItems": 50,
+  "type": "array"
+}

addedInput schema / properties / visitor_id

Added value: +{
+  "description": "One visitor's journey, visitor_id from an earlier row or from list_events.",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "site"
-]New value: +[
+  "site_id",
+  "from",
+  "to"
+]

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "properties": {
+    "journeys": {
+      "description": "Journeys on this page, in the requested sort.",
+      "items": {
+        "additionalProperties": false,
+        "description": "One journey.",
+        "properties": {
+          "ended_at": {
+            "description": "Time of the visitor's latest event in the range.",
+            "format": "date-time",
+            "type": "string"
+          },
+          "event_counts": {
+            "additionalProperties": {
+              "type": "integer"
+            },
+            "description": "Count of each event in the journey, including the latest, by event name, such as `{ \"PageView\": 10, \"Purchase\": 2 }`.",
+            "type": "object"
+          },
+          "first_touch": {
+            "additionalProperties": false,
+            "description": "First visit credited, as stored on the journey's latest event: `source` (string, such as facebook or organic), `utm_campaign`, `utm_term` (usually the ad set), `utm_content` (usually the ad), `utm_medium`, `utm_id` (string or null each). null on a row with no visitor id, or when none was stored.",
+            "properties": {
+              "source": {
+                "description": "Source, such as facebook or organic.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_campaign": {
+                "description": "UTM campaign.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_content": {
+                "description": "UTM content (usually the ad).",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_id": {
+                "description": "UTM id.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_medium": {
+                "description": "UTM medium.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_term": {
+                "description": "UTM term (usually the ad set).",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "source",
+              "utm_campaign",
+              "utm_term",
+              "utm_content",
+              "utm_medium",
+              "utm_id"
+            ],
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "has_earlier_touchpoints": {
+            "description": "true when the journey has more than 50 events, so earlier ones are not in touchpoints. event_counts still counts all of them.",
+            "type": "boolean"
+          },
+          "id": {
+            "description": "Row id of the single event on a row with no visitor id, as id in list_events; get_event_payloads takes it in ids. null on visitor rows.",
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "last_touch": {
+            "additionalProperties": false,
+            "description": "Last visit credited, as stored on the journey's latest event. Same fields as first_touch. null on a row with no visitor id, or when none was stored.",
+            "properties": {
+              "source": {
+                "description": "Source, such as facebook or organic.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_campaign": {
+                "description": "UTM campaign.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_content": {
+                "description": "UTM content (usually the ad).",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_id": {
+                "description": "UTM id.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_medium": {
+                "description": "UTM medium.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_term": {
+                "description": "UTM term (usually the ad set).",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "source",
+              "utm_campaign",
+              "utm_term",
+              "utm_content",
+              "utm_medium",
+              "utm_id"
+            ],
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "started_at": {
+            "description": "Time of the first event in the journey, at most lookback_days before ended_at.",
+            "format": "date-time",
+            "type": "string"
+          },
+          "touchpoints": {
+            "description": "The journey's last 50 events, oldest first: `event` (string, such as PageView) and `time` (string, date-time, in timezone).",
+            "items": {
+              "additionalProperties": false,
+              "description": "One event.",
+              "properties": {
+                "event": {
+                  "description": "Event name.",
+                  "type": "string"
+                },
+                "time": {
+                  "description": "When the event arrived.",
+                  "format": "date-time",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "event",
+                "time"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "values": {
+            "description": "Value of the journey's conversions, summed per currency: `currency` (string or null), `amount` (number). Empty when none carried a value.",
+            "items": {
+              "additionalProperties": false,
+              "description": "One currency.",
+              "properties": {
+                "amount": {
+                  "description": "Summed value.",
+                  "type": "number"
+                },
+                "currency": {
+                  "description": "Currency code.",
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              },
+              "required": [
+                "currency",
+                "amount"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "visitor_id": {
+            "description": "Visitor this journey belongs to. null when the row is one event with no visitor id, so earlier visits could not be linked.",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "visitor_id",
+          "id",
+          "started_at",
+          "ended_at",
+          "event_counts",
+          "touchpoints",
+          "has_earlier_touchpoints",
+          "values",
+          "first_touch",
+          "last_touch"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "lookback_days": {
+      "description": "Days before a visitor's last event that their journey covers.",
+      "type": "integer"
+    },
+    "next_page": {
+      "description": "Pass as page for the next page, with the same filters and sort. null: last page.",
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "sort": {
+      "description": "Sort used.",
+      "enum": [
+        "most_recent",
+        "highest_value"
+      ],
+      "type": "string"
+    },
+    "timezone": {
+      "description": "IANA time zone used for dates and times. UTC when none was passed.",
+      "type": "string"
+    },
+    "total": {
+      "description": "Journeys matching the filters, across all pages.",
+      "type": "integer"
+    },
+    "window": {
+      "additionalProperties": false,
+      "description": "Exact range read, after applying timezone.",
+      "properties": {
+        "from": {
+          "description": "First instant included.",
+          "format": "date-time",
+          "type": "string"
+        },
+        "to": {
+          "description": "Last instant included.",
+          "format": "date-time",
+          "type": "string"
+        }
+      },
+      "required": [
+        "from",
+        "to"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "window",
+    "timezone",
+    "sort",
+    "lookback_days",
+    "total",
+    "next_page",
+    "journeys"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedOct 27, 2026

changedInput schema / properties / from / description

Previous value: -"Range start, ISO date. Omit when journey_id is set"New value: +"Range start. YYYY-MM-DD is the start of that calendar day in timezone. A full ISO instant is that instant. Omit when journey_id is set"

changedInput schema / properties / to / description

Previous value: -"Range end, ISO date. Omit when journey_id is set"New value: +"Range end. YYYY-MM-DD is the end of that calendar day in timezone, so later events that day are included. A full ISO instant is that instant. Omit when journey_id is set"

First observedOct 23, 2026

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds substantial behavior beyond them: per-currency value, event counts, the last 50 events with timestamps, first/last touch credit, the lookback_days window ending at the visitor's last in-range event, orphan events forming their own rows, and a plan-based refusal condition. These are exactly the quirks an agent needs to interpret or explain results correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with the output shape and the journey definition, then closes with the when-to-use routing sentence. Dense and mostly waste-free, though the row-contents sentence mildly duplicates what the output schema already conveys.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 13 parameters, an output schema, and full annotation coverage, the description supplies everything an agent needs to select and call the tool: scope, row semantics, default filter behavior, and the plan-limit failure mode. Return-format detail is optional here since an output schema exists, yet the description still describes row contents usefully.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description adds genuine meaning on top: it explains what `events` defaults to (conversion events) and the effect of adding PageView, plus how `from`/`to` define the journey window relative to the visitor's last event. Remaining parameters (sort, page, limit, utm_*) are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a concrete verb and resource ('Get visitor journeys on one site') and pins down the row granularity ('one row per visitor with an event in the date range'), which separates it in practice from an event-level list like list_events. It does not explicitly name or route away from siblings such as get_attribution or list_events, so the differentiation is implied rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is stated positively and concretely: 'Use it when the user asks about customer, user, or conversion journeys: what visitors did on the site before they converted, and which first and last touch the conversion is credited to.' It also flags a prerequisite/limit ('Ranges before the plan's journey lookback are refused') and a useful default override ('Add PageView to include visitors who did not convert'). It lacks explicit when-not-to-use guidance relative to get_attribution or list_events.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All PixelFlow tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.