Account Journey API | Factors.ai Help Center

Introduction

The Account Journey API provides a chronological view of user activities associated with a specific account (identified by its domain name) within a given Factors project. It allows external systems or developers to retrieve detailed timelines of interactions performed by users linked to that account, optionally filtered by time range, event name, and user name.

This is the same data that can be found in the 'account birdview' section in the product

API Endpoint Details

Method & Path

Method: GET
Path: /open/v1/account/:account_domain/journey

Parameters

Path Parameters:
- account_domain (string, required): The domain name representing the account (e.g., factors.ai, acme.com). This is used to identify the target account within the project.
Query Parameters:
- from (string, optional): The start timestamp for the timeline data filter.
  - Format: Supports YYYY-MM-DD HH:MM:SS.ffffff (e.g., 2023-10-01 00:00:00.000000) or YYYY-MM-DD (e.g., 2023-10-01).
  - Default: If omitted, defaults to 30 days before the current time.
  - Note: If YYYY-MM-DD is used, the time is considered 00:00:00 of that day.
- to (string, optional): The end timestamp for the timeline data filter.
  - Format: Supports YYYY-MM-DD HH:MM:SS.ffffff (e.g., 2023-10-27 23:59:59.999999) or YYYY-MM-DD (e.g., 2023-10-27).
  - Default: If omitted, defaults to the current time.
  - Note: If YYYY-MM-DD is used, the time is considered 23:59:59 of that day.
- event_name (string, optional): Filters the activities to include only those where the event name contains the provided string (case-insensitive substring match).
- user_name (string, optional): Filters the timelines to include only those users where the user's name contains the provided string (case-insensitive substring match). User name is derived from user properties (e.g., $name) or customer user ID.

Authentication & Authorization

Method: Bearer Token Authentication.
Header: Authorization: Bearer <your_private_token>
Token Generation: The <your_private_token> must be generated specifically for the agent making the call against the target project.

If no valid mapping is found or the token is missing/invalid, a 401 Unauthorized error is returned.

Request Payload

N/A. This is a GET request, and all parameters are passed via the path or query string.

5. Response Payload

Success Response (200 OK)

Content-Type: application/json

Body: A JSON array of UserTimeline objects. Each object represents a distinct user associated with the account domain who performed activities within the filtered timeframe and matched optional filters.

[
  { // UserTimeline Object 1
    "user_id": "user123",
    "is_anonymous": false,
    "user_name": "Alice Smith",
    "user_properties": "{\"email\":\"alice@example.com\", \"$initial_source\":\"google\"}", // JSONB string
    "filtered_user_properties": { // Map derived from user_properties based on config
        "email": "alice@example.com"
    },
    "user_activities": [ // Array of UserActivity objects for this user
      { // UserActivity Object 1.1
        "event_id": "evt_abc",
        "event_name": "$session",
        "event_type": "EVNAME_TYPE_SESSION",
        "timestamp": 1698350000,
        "properties": "{\"utm_source\":\"google\"}", // JSONB string
        "display_name": "Session Started",
        "alias_name": "Session Started",
        "icon": "desktop"
      },
      { // UserActivity Object 1.2
        "event_id": "evt_def",
        "event_name": "signup_completed",
        "event_type": "EVNAME_TYPE_USER_CREATED",
        "timestamp": 1698350120,
        "properties": "{\"plan\":\"free\"}", // JSONB string
        "display_name": "Signup Completed",
        "alias_name": "Signup Completed",
        "icon": "check_circle"
      }
      // ... more activities for User 1
    ],
    "user_last_event_at": "2023-10-27T12:05:20Z", // Timestamp of the last activity
    "extra_prop": "All" // Static value, purpose unclear from code alone
  },
  { // UserTimeline Object 2 (e.g., an anonymous user)
    "user_id": "anon_xyz789",
    "is_anonymous": true,
    "user_name": "anon_xyz789",
    "user_properties": "{\"$initial_page_url\":\"https://factors.ai/pricing\"}", // JSONB string
     "filtered_user_properties": {
         "$initial_page_url": "https://factors.ai/pricing"
     },
    "user_activities": [
      { // UserActivity Object 2.1
         "event_id": "evt_ghi",
         "event_name": "$pageView",
         "event_type": "EVNAME_TYPE_AUTO_TRACKED",
         "timestamp": 1698349800,
         "properties": "{\"$page_url\":\"https://factors.ai/pricing\", \"$is_page_view\": true}", // JSONB string
         "display_name": "Page View",
         "alias_name": "https://factors.ai/pricing",
         "icon": "window"
      }
      // ... more activities for User 2
    ],
    "user_last_event_at": "2023-10-27T11:50:00Z",
    "extra_prop": "All"
  }
  // ... more UserTimeline objects
]

Error Response

Errors follow the standard structure defined by the responseWrapper.

Content-Type: application/json

Example (400 Bad Request):

{
  "error": "Invalid 'from' parameter format. Supported formats are RFC3339 and YYYY-MM-DD",
  "err": {
    "code": "INVALID_INPUT",
    "display_message": "Invalid Input.", // From V1.ErrorMessages
    "details": "",
    "tracking_id": "req_abc123xyz" // Example request ID
  }
}

Example (401 Unauthorized):

{
  "error": "invalid private token."
}

Example (404 Not Found - if domain or initial data not found):

{
  "error": "domain group not found", // Or "domainId not found" or "No activities found within the time range"
  "err": {
    "code": "PROCESSING_FAILED", // Or specific code if defined
    "display_message": "Processing failed.", // From V1.ErrorMessages
    "details": "",
    "tracking_id": "req_def456uvw"
  }
}

UserActivity

Represents a single event/action performed by a user.

Field	Type	Description	Example
`user_id`	string	The identifier for the user (either customer user ID or anonymous ID).	`"user123"`, `"anon_xyz789"`
`is_anonymous`	boolean	`true` if the `user_id` is an anonymous ID, `false` otherwise.	`false`, `true`
`user_name`	string	Display name for the user, typically `$name` property, customer user ID, or anonymous ID as fallback.	`"Alice Smith"`, `"anon_xyz789"`
`user_properties`	JSONB string	A JSON string containing the user's properties stored in the database.	`"{\"$email\":\"alice@example.com\",\"plan\":\"enterprise\"}"`
`filtered_user_properties`	map[string]interface{}	A map containing key-value pairs of user properties configured for display in the timeline UI (left pane).	`{"email": "alice@example.com", "plan": "enterprise"}`
`user_activities`	array[UserActivity]	An array of activities performed by this user within the specified timeframe and matching filters.	`[ { ... }, { ... } ]`
`user_last_event_at`	string (ISO 8601)	Timestamp of the last event recorded for this user (used for ordering).	`"2023-10-27T12:05:20Z"`
`extra_prop`	string	Static value "All", purpose unclear from the handler logic itself, possibly for UI compatibility.	`"All"`

UserActivity

Represents a single event/action performed by a user.

Field	Type	Description	Example
`event_id`	string	The unique identifier for this specific event occurrence.	`"evt_abc"`
`event_name`	string	The name of the event as recorded (e.g., `$session`, `signup_completed`, `$pageView`).	`"$session"`
`event_type`	string	The type classification of the event (e.g., `EVNAME_TYPE_SESSION`, `EVNAME_TYPE_USER_CREATED`).	`"EVNAME_TYPE_SESSION"`
`timestamp`	integer (Unix)	The time the event occurred, as a Unix timestamp (seconds).	`1698350000`
`properties`	JSONB string	A JSON string containing properties associated with this specific event occurrence.	`"{\"utm_source\":\"google\",\"duration\": 300}"`, `"{}"`
`display_name`	string	A user-friendly name for the event, potentially derived from configuration or standard names.	`"Session Started"`, `"Page View"`
`alias_name`	string	An alternative name, often the page URL for page views or the event name itself otherwise.	`"Session Started"`, `"https://factors.ai/pricing"`
`icon`	string	A string identifier for a UI icon representing the event type (e.g., `desktop`, `window`).	`"desktop"`