Skip to main content
v1.0GuidesGuidesAPI ReferenceAPI Reference

Revenue Server

Track revenue attribution and milestone conversions (MQL, SQL, Paid Conversion) to understand which marketing activities drive the most valuable outcomes.

Overview​

The Revenue Server specializes in revenue attribution and conversion analysis. It helps you track and analyze how marketing efforts contribute to revenue generation through various milestones like MQL, SQL, and Conversions.

Server Details​

  • Server Name: revenue-server
  • Version: 0.0.1
  • Endpoint: /mcp/revenue
  • Authentication: Organization-level required

Purpose​

Analyze revenue attribution, milestone conversions, and marketing influence on revenue generation. This server is ideal for understanding which marketing activities drive the most valuable outcomes.

Available Tools​

1. milestones-tool​

Purpose: Retrieve configured milestones for your organization

When to use:

  • At the start of any revenue analysis conversation
  • To validate milestone names before querying
  • To identify which milestones are configured as MQL, SQL, or Conversion

Returns: A table of available milestones with their flags (MQL, SQL, Conversion)

Example Response:

| Milestone | MQL | SQL | Conversion |
|-----------|-----|-----|------------|
| Signup    | ✓   |     |            |
| Demo Request |  | ✓   |            |
| Paid Conversion | | | ✓          |

2. terminology-tool​

Purpose: Translate abbreviations and business terms

When to use:

  • User mentions abbreviations (MQL, SQL, PTC, etc.)
  • Need to understand attribution model types
  • Clarify business metrics terminology

Returns: Comprehensive guide of terminologies and their meanings

3. system-report-schema-tool​

Purpose: Get field mappings for the SystemReport index

When to use:

  • Before constructing any query
  • To discover available fields and their types
  • To validate field names

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

4. system-report-compute-tool​

Purpose: Execute Elasticsearch queries against the SystemReport index

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

Example Query:

{
  "query": {
    "bool": {
      "filter": [
        {"exists": {"field": "Signup"}},
        {"range": {"First Touch Date": {"gte": "now-30d/d"}}}
      ]
    }
  },
  "size": 100
}

5. chart-format-tool​

Purpose: Generate Chart.js configurations for data visualization

Supported chart types: line, pie, doughnut, bar, horizontalBar

Example Usage:

{
  "type": "line",
  "title": "Revenue Trend",
  "height": 400,
  "unit": "day"
}

Key Concepts​

Milestones​

Milestones represent key conversion points in your customer journey:

  • MQL (Marketing Qualified Lead): A lead qualified by marketing
  • SQL (Sales Qualified Lead): A lead qualified by sales
  • Conversion: Final conversion event (purchase, signup, etc.)

Milestone to Query Field Mapping​

When filtering by milestones, use the milestone's exact name as the field name in queries.

Example:

  • If MQL milestone is "Signup" → Use {"exists": {"field": "Signup"}}
  • If SQL milestone is "Demo Request" → Use {"exists": {"field": "Demo Request"}}
  • If Conversion milestone is "Paid Conversion" → Use {"exists": {"field": "Paid Conversion"}}

Date Filtering​

IMPORTANT: Always apply date filters to queries for accurate and performant results.

Example date filters:

{
  "range": {
    "First Touch Date": {
      "gte": "now-30d/d",
      "lte": "now/d"
    }
  }
}

Common Use Cases​

1. MQL Count for Last 30 Days​

Workflow:

  1. Call milestones-tool to find MQL milestone name (e.g., "Signup")
  2. Call system-report-compute-tool with query:
{
  "query": {
    "bool": {
      "filter": [
        {"exists": {"field": "Signup"}},
        {"range": {"Signup": {"gte": "now-30d/d"}}}
      ]
    }
  },
  "size": 0,
  "aggs": {
    "total_mqls": {
      "value_count": {"field": "Signup"}
    }
  }
}

2. Conversion Rate by Channel​

Workflow:

  1. Call milestones-tool to identify MQL and Conversion milestones
  2. Call system-report-compute-tool:
{
  "query": {
    "range": {"First Touch Date": {"gte": "now-90d/d"}}
  },
  "size": 0,
  "aggs": {
    "by_channel": {
      "terms": {"field": "First Touch Channel.keyword", "size": 20},
      "aggs": {
        "mqls": {
          "filter": {"exists": {"field": "Signup"}}
        },
        "conversions": {
          "filter": {"exists": {"field": "Paid Conversion"}}
        }
      }
    }
  }
}

3. Revenue Trend Over Time​

{
  "query": {
    "range": {"Paid Conversion": {"gte": "now-90d/d"}}
  },
  "size": 0,
  "aggs": {
    "revenue_by_day": {
      "date_histogram": {
        "field": "Paid Conversion",
        "calendar_interval": "day"
      },
      "aggs": {
        "total_revenue": {
          "sum": {"field": "Revenue"}
        }
      }
    }
  }
}

4. Top Performing Campaigns​

{
  "query": {
    "bool": {
      "filter": [
        {"exists": {"field": "Paid Conversion"}},
        {"range": {"Paid Conversion": {"gte": "now-30d/d"}}}
      ]
    }
  },
  "size": 0,
  "aggs": {
    "by_campaign": {
      "terms": {
        "field": "First Touch UTM Campaign.keyword",
        "size": 10,
        "order": {"total_revenue": "desc"}
      },
      "aggs": {
        "total_revenue": {
          "sum": {"field": "Revenue"}
        },
        "conversion_count": {
          "value_count": {"field": "Paid Conversion"}
        }
      }
    }
  }
}

Best Practices​

1. Always Call milestones-tool First​

Before any revenue analysis, call the milestones tool to get the correct milestone names and their configurations.

2. Use Exact Milestone Names​

When filtering by milestones, use the exact name (including casing and spacing) from the milestones tool.

3. Apply Date Filters​

Always include date range filters to improve query performance and ensure relevant results.

4. Text Search with Wildcards​

Use wildcard matching for text searches unless exact match is explicitly requested:

{"wildcard": {"First Touch UTM Campaign": "*brand*"}}

5. Handle Missing Milestones​

If a user asks about MQL/SQL/Conversion and no milestone is configured with that flag, inform them to configure it at: https://platform.sonalabs.com/setup/profile/milestones

Query Tips​

Filtering by Multiple Conditions​

{
  "query": {
    "bool": {
      "filter": [
        {"exists": {"field": "Signup"}},
        {"term": {"First Touch Channel.keyword": "Paid Search"}},
        {"range": {"Signup": {"gte": "now-30d/d"}}}
      ]
    }
  }
}

Excluding Null Values​

{
  "query": {
    "bool": {
      "must": [
        {"exists": {"field": "Revenue"}},
        {"range": {"Revenue": {"gt": 0}}}
      ]
    }
  }
}

Calculating Conversion Rates​

Use bucket_script in aggregations:

{
  "aggs": {
    "by_source": {
      "terms": {"field": "First Touch Utm Source.keyword"},
      "aggs": {
        "mqls": {"filter": {"exists": {"field": "Signup"}}},
        "conversions": {"filter": {"exists": {"field": "Paid Conversion"}}},
        "conversion_rate": {
          "bucket_script": {
            "buckets_path": {
              "mqls": "mqls>_count",
              "conversions": "conversions>_count"
            },
            "script": "params.mqls > 0 ? (params.conversions / params.mqls) * 100 : 0"
          }
        }
      }
    }
  }
}
Last updated on by Sona