Skip to main content
v1.0GuidesGuidesAPI ReferenceAPI Reference

Data Activation Visitors Server

Analyze identified visitor behavior — sessions, pages viewed, engagement metrics, and individual journeys — to find your highest-value prospects.

Overview​

The Data Activation Visitors Server specializes in analyzing identified visitor data. It helps you understand visitor behavior, session patterns, engagement metrics, and individual visitor journeys.

Server Details​

  • Server Name: data-activation-visitors-server
  • Version: 0.0.1
  • Endpoint: /mcp/data-activation-visitors
  • Authentication: Organization-level required

Purpose​

Analyze identified visitors, track their session behavior, engagement patterns, page views, and understand individual visitor journeys to identify high-value prospects and engagement opportunities.

Available Tools​

1. visitors-schema-tool​

Purpose: Get field mappings for the Visitors index

When to use: Before constructing queries to understand available fields

Returns: Elasticsearch mapping with field names, types, and descriptions

2. visitors-compute-tool​

Purpose: Execute Elasticsearch queries against the Visitors index

Input: Elasticsearch query JSON Returns: Query results with matching visitors and aggregations

3. terminology-tool​

Purpose: Translate abbreviations and business terms

Purpose: Generate clickable links to visitor profiles

Input:

{
  "visitors": [
    {"id": "visitor-123", "label": "John Doe"},
    {"id": "visitor-456", "label": "Jane Smith"}
  ]
}

Returns: Array of clickable links to visitor detail pages

5. chart-format-tool​

Purpose: Generate Chart.js configurations for visualizing visitor data

Key Fields​

Identity Fields​

  • id - Unique visitor identifier
  • email - Visitor email address
  • name - Visitor name
  • firstName - First name
  • lastName - Last name
  • title - Job title
  • phone - Phone number

Company Fields​

  • company - Company name
  • companyDomain - Company domain
  • companyUuid - Associated company UUID

Session Fields​

  • sessionId - Session identifier
  • sessionStart - Session start timestamp
  • sessionEnd - Session end timestamp
  • sessionDuration - Session duration (seconds)

Engagement Fields​

  • pageViews - Number of page views
  • uniquePages - Number of unique pages visited
  • totalActiveTime - Total active time on site (seconds)
  • urls - Array of URLs visited
  • lastVisitDate - Most recent visit date
  • firstVisitDate - First visit date

Attribution Fields​

  • utmSource - UTM source
  • utmMedium - UTM medium
  • utmCampaign - UTM campaign
  • utmContent - UTM content
  • utmTerm - UTM term
  • referrer - Referrer URL
  • landingPage - Landing page URL

Device/Location Fields​

  • device - Device type (desktop, mobile, tablet)
  • browser - Browser name
  • os - Operating system
  • city - City
  • state - State/province
  • country - Country
  • ipAddress - IP address

Behavioral Fields​

  • engagementScore - Engagement score
  • intentScore - Intent score
  • isIdentified - Whether visitor is identified
  • identifiedDate - When visitor was identified

Common Use Cases​

1. Recently Identified Visitors​

{
  "query": {
    "bool": {
      "filter": [
        {"term": {"isIdentified": true}},
        {"range": {"identifiedDate": {"gte": "now-7d/d"}}}
      ]
    }
  },
  "_source": ["id", "name", "email", "company", "title", "identifiedDate", "pageViews"],
  "sort": [{"identifiedDate": "desc"}],
  "size": 50
}

2. High-Engagement Visitors​

{
  "query": {
    "bool": {
      "filter": [
        {"range": {"pageViews": {"gte": 10}}},
        {"range": {"totalActiveTime": {"gte": 300}}},
        {"range": {"lastVisitDate": {"gte": "now-14d/d"}}}
      ]
    }
  },
  "_source": ["id", "name", "email", "company", "pageViews", "totalActiveTime", "urls"],
  "sort": [{"pageViews": "desc"}],
  "size": 100
}

3. Visitors by Company​

{
  "query": {
    "wildcard": {"companyDomain": "*acme.com"}
  },
  "_source": ["id", "name", "email", "title", "company", "pageViews", "lastVisitDate"],
  "sort": [{"lastVisitDate": "desc"}],
  "size": 50
}

4. Visitors Viewing Specific Pages​

{
  "query": {
    "bool": {
      "should": [
        {"wildcard": {"urls": "*pricing*"}},
        {"wildcard": {"urls": "*demo*"}},
        {"wildcard": {"urls": "*contact*"}}
      ],
      "minimum_should_match": 1,
      "filter": [
        {"term": {"isIdentified": true}}
      ]
    }
  },
  "_source": ["id", "name", "email", "company", "urls", "lastVisitDate"],
  "size": 100
}

5. Visitors by UTM Campaign​

{
  "query": {
    "term": {"utmCampaign.keyword": "Q1-Brand-Campaign"}
  },
  "size": 0,
  "aggs": {
    "total_visitors": {
      "cardinality": {"field": "id.keyword"}
    },
    "identified_visitors": {
      "filter": {"term": {"isIdentified": true}}
    },
    "avg_page_views": {
      "avg": {"field": "pageViews"}
    },
    "avg_active_time": {
      "avg": {"field": "totalActiveTime"}
    }
  }
}

6. Visitor Engagement Trend​

{
  "query": {
    "range": {"lastVisitDate": {"gte": "now-30d/d"}}
  },
  "size": 0,
  "aggs": {
    "visits_by_day": {
      "date_histogram": {
        "field": "lastVisitDate",
        "calendar_interval": "day"
      },
      "aggs": {
        "unique_visitors": {
          "cardinality": {"field": "id.keyword"}
        },
        "total_page_views": {
          "sum": {"field": "pageViews"}
        }
      }
    }
  }
}

7. Visitors by Job Title​

{
  "query": {
    "bool": {
      "should": [
        {"wildcard": {"title": "*director*"}},
        {"wildcard": {"title": "*vp*"}},
        {"wildcard": {"title": "*manager*"}}
      ],
      "minimum_should_match": 1,
      "filter": [
        {"term": {"isIdentified": true}}
      ]
    }
  },
  "_source": ["id", "name", "email", "title", "company", "pageViews"],
  "size": 100
}

8. Visitors by Device Type​

{
  "query": {
    "range": {"lastVisitDate": {"gte": "now-30d/d"}}
  },
  "size": 0,
  "aggs": {
    "by_device": {
      "terms": {"field": "device.keyword", "size": 10},
      "aggs": {
        "unique_visitors": {
          "cardinality": {"field": "id.keyword"}
        },
        "avg_page_views": {
          "avg": {"field": "pageViews"}
        },
        "avg_session_duration": {
          "avg": {"field": "sessionDuration"}
        }
      }
    }
  }
}

9. Visitors by Geographic Location​

{
  "query": {
    "bool": {
      "filter": [
        {"term": {"country.keyword": "United States"}},
        {"term": {"isIdentified": true}}
      ]
    }
  },
  "size": 0,
  "aggs": {
    "by_state": {
      "terms": {"field": "state.keyword", "size": 20},
      "aggs": {
        "visitor_count": {
          "cardinality": {"field": "id.keyword"}
        },
        "avg_engagement": {
          "avg": {"field": "engagementScore"}
        }
      }
    }
  }
}

10. High-Intent Visitors​

{
  "query": {
    "bool": {
      "filter": [
        {"range": {"intentScore": {"gte": 70}}},
        {"term": {"isIdentified": true}},
        {"range": {"lastVisitDate": {"gte": "now-14d/d"}}}
      ]
    }
  },
  "_source": ["id", "name", "email", "company", "title", "intentScore", "pageViews", "urls"],
  "sort": [{"intentScore": "desc"}],
  "size": 50
}

11. Session Analysis​

{
  "query": {
    "bool": {
      "filter": [
        {"range": {"sessionStart": {"gte": "now-7d/d"}}},
        {"range": {"sessionDuration": {"gte": 60}}}
      ]
    }
  },
  "_source": ["id", "name", "email", "sessionId", "sessionStart", "sessionDuration", "pageViews"],
  "sort": [{"sessionDuration": "desc"}],
  "size": 100
}

12. Repeat Visitors​

{
  "query": {
    "bool": {
      "filter": [
        {"range": {"pageViews": {"gte": 5}}},
        {"exists": {"field": "firstVisitDate"}},
        {"exists": {"field": "lastVisitDate"}}
      ]
    }
  },
  "size": 0,
  "aggs": {
    "by_visitor": {
      "terms": {"field": "id.keyword", "size": 100},
      "aggs": {
        "total_page_views": {
          "sum": {"field": "pageViews"}
        },
        "visit_count": {
          "value_count": {"field": "sessionId.keyword"}
        }
      }
    }
  }
}

Best Practices​

1. Always Check Schema First​

Call visitors-schema-tool before querying to ensure correct field names.

2. Use Wildcard for Text Search​

Unless exact match is explicitly requested:

{"wildcard": {"name": "*john*"}}

3. Filter for Identified Visitors​

For most analyses, focus on identified visitors:

{"term": {"isIdentified": true}}

4. Include Key Fields in _source​

Always include: id, name, email, company for generating visitor links.

5. Use .keyword for Exact Matches​

For text fields that need exact matching:

{"term": {"company.keyword": "Acme Corp"}}

6. Apply Date Filters​

For time-sensitive queries:

{"range": {"lastVisitDate": {"gte": "now-30d/d"}}}

After retrieving visitors, call visitor-links-tool to provide easy access.

8. Combine Engagement Metrics​

Use multiple engagement signals for better insights:

{
  "query": {
    "bool": {
      "filter": [
        {"range": {"pageViews": {"gte": 5}}},
        {"range": {"totalActiveTime": {"gte": 180}}},
        {"range": {"uniquePages": {"gte": 3}}}
      ]
    }
  }
}

Query Patterns​

Multiple Filters Combined​

{
  "query": {
    "bool": {
      "filter": [
        {"term": {"isIdentified": true}},
        {"range": {"pageViews": {"gte": 5}}},
        {"wildcard": {"title": "*director*"}},
        {"range": {"lastVisitDate": {"gte": "now-14d/d"}}}
      ]
    }
  }
}

Text Search Across Multiple Fields​

{
  "query": {
    "bool": {
      "should": [
        {"wildcard": {"name": "*search*term*"}},
        {"wildcard": {"email": "*search*term*"}},
        {"wildcard": {"company": "*search*term*"}}
      ],
      "minimum_should_match": 1
    }
  }
}

Aggregations for Insights​

{
  "size": 0,
  "aggs": {
    "engagement_distribution": {
      "histogram": {"field": "engagementScore", "interval": 10}
    },
    "top_companies": {
      "terms": {"field": "company.keyword", "size": 20}
    },
    "avg_metrics": {
      "stats": {"field": "pageViews"}
    }
  }
}

Sorting by Multiple Fields​

{
  "sort": [
    {"intentScore": "desc"},
    {"pageViews": "desc"},
    {"lastVisitDate": "desc"}
  ]
}

Workflow Example​

Goal: Find high-engagement visitors from target companies who viewed pricing pages

Step 1: Check schema

Call: visitors-schema-tool

Step 2: Query visitors

{
  "query": {
    "bool": {
      "filter": [
        {"term": {"isIdentified": true}},
        {"range": {"pageViews": {"gte": 5}}},
        {"wildcard": {"urls": "*pricing*"}},
        {"range": {"lastVisitDate": {"gte": "now-14d/d"}}}
      ]
    }
  },
  "_source": ["id", "name", "email", "company", "title", "pageViews", "urls", "lastVisitDate"],
  "sort": [{"pageViews": "desc"}],
  "size": 50
}

Step 3: Generate links

{
  "visitors": [
    {"id": "visitor-123", "label": "John Doe - Acme Corp"},
    {"id": "visitor-456", "label": "Jane Smith - TechCo"}
  ]
}

Step 4: Present results with insights

  • Show visitor names as clickable links
  • Highlight engagement metrics
  • Note pages viewed (especially pricing)
  • Provide recommendations for follow-up
Last updated on by Sona