# RevCent MCP Operation: `GetTrackingVisitor`

AI/MCP-focused operation guide for retrieving a single Tracking Visitor in RevCent.

---

## Operation Summary

Operation:

```text
GetTrackingVisitor
```

Title:

```text
Get A Tracking Visitor
```

Purpose:

```text
Retrieve the details of a specific tracking visitor.
```

A Tracking Visitor represents a tracked website visitor associated with a RevCent Tracking Domain. The record can include visitor-level metadata, IP/user-agent details, related Sales if the visitor purchased, and page-visit tracking entries showing the visitor's path through the tracked site.

---

## Refreshed Operation List Confirmation

After refreshing the MCP operation list, `GetTrackingVisitor` is available as a RevCent MCP operation.

Related tracking and reporting operations available in the MCP include:

```text
GetTrackingDomains
CreateTrackingDomain
GetTrackingDomain
EditTrackingDomain
InitializeTrackingDomainSSL
InitializeTrackingDomainDNS
GetTrackingVisitor
GetSale
GetSales
GetBigQueryTables
BigQueryRunQuery
```

---

## When to Use

Use `GetTrackingVisitor` when AI/MCP has a specific 20-character Tracking Visitor ID and needs to inspect that visitor.

Good use cases:

```text
Review a visitor's path to purchase.
Inspect which Tracking Domain created the visitor.
See the visitor's page visits.
Check whether the visitor made a purchase.
Retrieve related Sale IDs for a tracked visitor.
Review visitor metadata saved from URL parameters.
Investigate fraud/risk/attribution context for one visitor.
```

Do not use `GetTrackingVisitor` for reporting, aggregation, bulk analysis, attribution summaries, visitor counts, funnel analysis, or page-visit metrics. Use BigQuery for those.

---

## Input Schema

Required field:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `tracking_visitor_id` | string | Yes | A 20-character Tracking Visitor ID. |

Example:

```json
{
  "tracking_visitor_id": "TVTVTVTVTVTVTVTVTVTV"
}
```

The schema uses:

```text
additionalProperties: false
```

Do not send unknown fields.

---

## Output Summary

A successful response can include:

| Field | Description |
|---|---|
| `api_call_id` | 20-character API call ID. |
| `api_call_unix` | Unix timestamp when the API call was initiated. |
| `code` | API response code. `1` means success. |
| `created_date_unix` | Unix timestamp when the visitor was created. |
| `id` | 20-character Tracking Visitor ID. |
| `ip_address` | Visitor IP address. |
| `user_agent` | Visitor user agent. |
| `tracking_domain` | Tracking Domain associated with the visitor. |
| `tracking_entries` | Page visits associated with the visitor. Max 50 entries returned. |
| `sales` | Sales associated with the visitor, if the visitor made a purchase. |
| `metadata` | Visitor metadata name/value pairs. |
| `updated_date_unix` | Unix timestamp when the visitor was last updated. |

---

## Tracking Visitor Relationship Model

Conceptual model:

```text
Tracking Domain
    ↓
Tracking Visitor
    ↓
Tracking Entries / Page Visits
    ↓
Sale(s), if the visitor purchased
```

A Tracking Visitor is created through RevCent tracking behavior on a Tracking Domain.

The Tracking Visitor can later be linked to a Sale if that visitor completes a purchase.

---

## Relationship to Tracking Domains

Tracking Visitors are tied to Tracking Domains.

The `tracking_domain` object in the `GetTrackingVisitor` response can include:

| Field | Description |
|---|---|
| `id` | 20-character Tracking Domain ID. |
| `name` | Tracking Domain name. |
| `domain` | Tracking Domain domain. |

Example response shape:

```json
{
  "tracking_domain": {
    "id": "TDTDTDTDTDTDTDTDTDTD",
    "name": "Acme Store Tracking Domain",
    "domain": "acmestore.com"
  }
}
```

Use `GetTrackingDomain` when more Tracking Domain detail is needed, such as DNS/SSL status, URL parameter sets, or manually configured URL parameters.

---

## Tracking Domains and DNS/SSL Setup

Tracking Domains enable RevCent's first-party DNS tracking.

Related operations:

```text
CreateTrackingDomain
InitializeTrackingDomainSSL
InitializeTrackingDomainDNS
GetTrackingDomain
EditTrackingDomain
```

Tracking Domain setup can include:

```text
root domain
SSL issuance
DNS initialization
A records
CNAME records
URL parameter sets
manual URL parameters
```

Important operational relationship:

```text
Tracking Visitor quality depends on the Tracking Domain being properly configured.
```

If DNS tracking is not correctly initialized, visitor tracking, visitor-to-sale attribution, URL parameter capture, and Sentinel visitor validation can be affected.

---

## URL Parameters and Metadata

Tracking Domains can save URL parameters to visitor metadata.

Examples:

```text
utm_source
utm_medium
utm_campaign
utm_content
utm_term
affiliate_id
click_id
subid
fbclid
gclid
```

The visitor response includes `metadata`, an array of name/value pairs:

```json
{
  "metadata": [
    {
      "name": "utm_source",
      "value": "facebook"
    },
    {
      "name": "campaign_id",
      "value": "spring_launch"
    }
  ]
}
```

Use metadata to understand attribution, campaign source, affiliate identifiers, click identifiers, and other URL-parameter-derived values attached to the visitor.

Recommended setup pattern:

```text
Create URL Parameter Set
    ↓
Attach URL Parameter Set to Tracking Domain using EditTrackingDomain.url_parameter_sets
    ↓
Visitors collect configured URL parameter metadata
    ↓
Visitor metadata can be used for attribution and reporting
```

---

## Associated Sales

If the visitor made a purchase, the `sales` array contains Sale IDs associated with the Tracking Visitor.

Response shape:

```json
{
  "sales": [
    {
      "id": "SSSSSSSSSSSSSSSSSSSS"
    }
  ]
}
```

Important:

```text
The sales array is present when the Tracking Visitor made a purchase.
```

Use `GetSale` to retrieve full details for each related Sale.

Recommended workflow:

```text
GetTrackingVisitor
    ↓
Read sales array
    ↓
For each Sale ID, call GetSale
    ↓
Review sale amount, customer, products, transactions, payment status, campaign, tracking_visitor, and metadata
```

The `GetSale` response also includes a `tracking_visitor` object when a Sale is associated with a Tracking Visitor.

Conceptual two-way relationship:

```text
Tracking Visitor → sales[] → GetSale
Sale → tracking_visitor.id → GetTrackingVisitor
```

---

## Tracking Entries / Page Visits

The `tracking_entries` array contains the Tracking Visitor's page visits.

Tracking entries are returned:

```text
in chronological order ascending
```

That means:

```text
first entry = first page visit
last entry = most recent page visit
```

The operation returns a maximum of:

```text
50 tracking entries
```

Each tracking entry can include:

| Field | Description |
|---|---|
| `created_date_unix` | Unix timestamp when the page visit occurred. |
| `hostname` | Hostname visited. |
| `pathname` | Pathname visited. |
| `referer` | Referrer for the visit. |
| `ip_address` | IP address for the page visit. |
| `tracking_domain` | Tracking Domain associated with the page visit. |

Example:

```json
{
  "tracking_entries": [
    {
      "created_date_unix": 1760000000,
      "hostname": "www.acmestore.com",
      "pathname": "/landing-page",
      "referer": "https://google.com",
      "ip_address": "203.0.113.10",
      "tracking_domain": {
        "id": "TDTDTDTDTDTDTDTDTDTD",
        "name": "Acme Store Tracking Domain",
        "domain": "acmestore.com"
      }
    }
  ]
}
```

---

## Path-to-Purchase Review

When a visitor made a purchase, `tracking_entries` can help reconstruct the path to purchase.

AI/MCP should summarize:

```text
first landing page
referrer/source if available
intermediate pages
checkout/cart pages
last page before purchase if evident
associated Sale IDs
visitor metadata such as UTM/click identifiers
```

Example summary pattern:

```text
Tracking Visitor TVTV... first landed on /facebook-offer from referer https://facebook.com.
The visitor then viewed /product/acme-kit and /checkout.
The visitor is associated with Sale SSSS..., which was successfully paid.
Metadata includes utm_source=facebook and utm_campaign=spring_launch.
```

Do not overstate causality. Page visits show sequence and context, not guaranteed attribution by themselves.

---

## Relationship to Sentinel Anti Fraud

Tracking Visitors can be important to Sentinel Anti Fraud.

Sentinel's tracking visitor validator can use visitor data to determine whether a purchase attempt should be treated as fraud.

Important:

```text
If tracking visitor validator is enabled, DNS Tracking should be set up for all domains.
```

If visitor validation is strict and tracking data is missing, purchases without valid visitor IDs may be treated as fraud depending on Sentinel settings.

Use Tracking Visitor data to support fraud/risk investigations, such as:

```text
visitor IP
user agent
page visit sequence
referrer
tracking domain
URL parameter metadata
associated sale(s)
```

---

## Common Workflows

### Retrieve Visitor and Associated Sale Details

```text
1. User provides tracking_visitor_id.
2. Run GetTrackingVisitor.
3. Review tracking_domain and tracking_entries.
4. If sales[] is non-empty, run GetSale for each Sale ID.
5. Summarize path-to-purchase and sale context.
```

### Review Page Visits Only

```text
1. Run GetTrackingVisitor.
2. Read tracking_entries.
3. Sort/interpret in returned chronological order.
4. Summarize landing page, referrer, sequence, and most recent page.
```

### Check Tracking Domain Context

```text
1. Run GetTrackingVisitor.
2. Read tracking_domain.id.
3. Run GetTrackingDomain if configuration detail is needed.
4. Review SSL/DNS status and URL parameter setup.
```

### Investigate Attribution Metadata

```text
1. Run GetTrackingVisitor.
2. Review metadata.
3. Review tracking_entries referer/hostname/pathname.
4. If purchased, retrieve associated Sale(s).
5. Use BigQuery for broader attribution reporting.
```

---

## BigQuery Reporting

Use BigQuery for reports involving Tracking Visitors.

Examples of reporting questions:

```text
How many tracking visitors did we have last week?
Which tracking domains have the most visitors?
Which landing pages produce the most purchases?
Show visitor-to-sale conversion by domain.
Show tracking visitors by UTM source.
Show page visit paths before purchase.
How many visitors had associated sales?
Which referrers are creating the most visitors?
```

Do not use `GetTrackingVisitor` for these reporting questions because it only retrieves one Tracking Visitor by ID.

Recommended reporting workflow:

```text
1. Run GetBigQueryTables.
2. Confirm the schema for tracking_visitor and related tracking/sale tables.
3. Build a BigQuery Standard SQL query.
4. Run BigQueryRunQuery.
5. If the query errors, fix it and run again.
```

---

## BigQuery Table Guidance

The primary table for Tracking Visitor reporting is expected to be:

```text
tracking_visitor
```

Reference it as:

```sql
`revcent.user.tracking_visitor`
```

Before running reports, AI/MCP should always use `GetBigQueryTables` to confirm:

```text
exact table names
available fields
field types
related sale/tracking entry tables
whether tracking entries are nested or separate
```

Do not assume field names beyond what `GetBigQueryTables` confirms.

---

## BigQuery Query Rules

When using `BigQueryRunQuery`:

```text
Use BigQuery Standard SQL.
Surround table references with backticks.
Use project ID revcent.
Use dataset ID user.
Avoid COALESCE.
When using TIMESTAMP_SUB, only use INTERVAL in DAY.
Optimize queries because query runs are limited to 30 seconds.
If a query error occurs, fix the query and run it again.
```

---

## Example BigQuery Report Patterns

These examples are conceptual. AI/MCP should confirm exact fields with `GetBigQueryTables` before running.

### Visitors by Day

```sql
SELECT
  DATE(TIMESTAMP_SECONDS(created_date_unix)) AS visitor_day,
  COUNT(*) AS visitors
FROM `revcent.user.tracking_visitor`
WHERE created_date_unix >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY))
GROUP BY visitor_day
ORDER BY visitor_day DESC
```

### Visitors by Tracking Domain

```sql
SELECT
  tracking_domain_id,
  tracking_domain_name,
  COUNT(*) AS visitors
FROM `revcent.user.tracking_visitor`
WHERE created_date_unix >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY))
GROUP BY tracking_domain_id, tracking_domain_name
ORDER BY visitors DESC
```

### Visitors With Associated Sales

```sql
SELECT
  COUNT(*) AS total_visitors,
  SUM(CASE WHEN sales_count > 0 THEN 1 ELSE 0 END) AS visitors_with_sales,
  SAFE_DIVIDE(SUM(CASE WHEN sales_count > 0 THEN 1 ELSE 0 END), COUNT(*)) AS visitor_to_sale_rate
FROM `revcent.user.tracking_visitor`
WHERE created_date_unix >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY))
```

### Visitors by UTM Source

```sql
SELECT
  utm_source,
  COUNT(*) AS visitors
FROM `revcent.user.tracking_visitor`
WHERE created_date_unix >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY))
GROUP BY utm_source
ORDER BY visitors DESC
```

Important:

```text
These examples must be adjusted to match actual BigQuery field names returned by GetBigQueryTables.
```

---

## Reporting vs Single Visitor Lookup

Use this decision rule:

| User Intent | Correct Operation |
|---|---|
| Retrieve one visitor by ID | `GetTrackingVisitor` |
| View one visitor's page visits | `GetTrackingVisitor` |
| Retrieve associated Sale IDs for one visitor | `GetTrackingVisitor`, then `GetSale` |
| Inspect Tracking Domain config | `GetTrackingDomain` |
| Count visitors | `BigQueryRunQuery` |
| Analyze landing pages/referrers | `BigQueryRunQuery` |
| Analyze visitor-to-sale conversion | `BigQueryRunQuery` |
| Analyze UTM/metadata performance | `BigQueryRunQuery` |

---

## Customer / Privacy Considerations

Tracking Visitor data may include IP address, user agent, referrer, metadata, page visits, and associated sales.

AI/MCP should treat this as potentially sensitive behavioral and attribution data.

Do not expose unnecessary visitor details in customer-facing messages.

When summarizing to an internal user, focus on the user's requested operational purpose.

---

## No-Human-in-the-Loop Guidance

If an external AI/agent uses this operation without a human in the loop:

```text
Use GetTrackingVisitor only when tracking_visitor_id is provided.
Do not attempt broad reporting with this operation.
Use BigQuery for reports.
Do not infer attribution beyond the available visitor entries and metadata.
```

If the visitor ID is missing, stop safely and return the missing requirement.

---

## Validation Checklist Before Calling

Before calling `GetTrackingVisitor`, confirm:

```text
tracking_visitor_id is present
tracking_visitor_id is a 20-character ID
The user/task is asking for one visitor, not a report
```

For reporting requests, use:

```text
GetBigQueryTables
BigQueryRunQuery
```

---

## Output Interpretation Checklist

After calling `GetTrackingVisitor`, review:

```text
visitor ID
created date
IP address
user agent
tracking domain
metadata
tracking entries / page visits
sales array
```

If sales are present:

```text
Use GetSale for each Sale ID when sale details are needed.
```

If tracking domain setup is relevant:

```text
Use GetTrackingDomain for the tracking_domain.id.
```

If the user asks for broader metrics:

```text
Use BigQuery.
```

---

## Final AI/MCP Instruction

Use `GetTrackingVisitor` to retrieve one specific Tracking Visitor and interpret its Tracking Domain, page visits, metadata, and associated Sales.

Use `GetSale` to inspect any associated Sales returned by the visitor.

Use `GetTrackingDomain` to inspect the domain configuration behind the visitor.

Use `GetBigQueryTables` and `BigQueryRunQuery` for reports using the `tracking_visitor` table and related tracking/sale tables.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.