Query API gives you access to sales and engagement data through three core objects: Accounts, Opportunities, and Users. This reference guide covers all available metrics, from activity tracking and health scores to performance indicators and predictive insights. Use it to discover the right metrics for your analysis, understand time-based variations, and build effective queries that deliver the insights you need.
⚠️ Important: Time-Based Metric Syntax
When using metrics with time periods, you MUST use the full slug + time period as the variation_id.
Pattern: {base_slug}_{time_period}
Example:
{
"slug": "ootb_user_count_emails_sent",
"variation_id": "ootb_user_count_emails_sent_last_30_days"
}
❌ WRONG: "variation_id": "last_30_days"
✅ CORRECT:"variation_id": "ootb_user_count_emails_sent_last_30_days"
Data Objects Overview
Object | Description | Primary Use Cases |
Account | Company-level data and metrics | Account health, pipeline value, engagement trends |
Opportunity | Deal-level data and metrics | Pipeline analysis, deal velocity, stage progression |
User | Sales rep and team member data | Performance tracking, activity metrics, quota attainment |
Account Object
Account-level metrics provide insights into company engagement, health, and pipeline data.
Core Account Fields
Field Name | Description | Data Type | Example Value |
ootb_account_crm_id | Unique CRM account identifier | String | "0011234567890AB" |
ootb_account_name | Account company name | String | "Acme Corporation" |
crm_account_owner | Account owner name | String | "John Smith" |
account_domain | Company domain | String | "acme.com" |
industry | Account industry classification | String | "Technology" |
company_size | Number of employees | Number | 500 |
annual_revenue | Company annual revenue | Number | 50000000 |
account_tier | Account tier/segment | String | "Enterprise" |
Account Health & Scoring Metrics
Metric Slug | Description | Data Type | Range | Variations |
ootb_account_engagement_level | Overall engagement level | Number | 0-100 | last_30_days, last_90_days, current_quarter |
ootb_relationship_strength | Relationship depth score | Number | 0-100 | Current |
ootb_buying_intent_score | Likelihood to purchase | Number | 0-100 | Current |
ootb_churn_risk_score | Risk of account churn | Number | 0-100 | Current |
Account Activity Metrics
Metric Slug | Description | Data Type | Variations |
ootb_emails_sent | Total emails sent to account | Number | last_7_days, last_30_days, current_quarter, current_year |
ootb_emails_received | Total emails received from account | Number | last_7_days, last_30_days, current_quarter, current_year |
ootb_meetings_held | Total meetings with account | Number | last_7_days, last_30_days, current_quarter, current_year |
ootb_calls_made | Total calls to account | Number | last_7_days, last_30_days, current_quarter, current_year |
ootb_last_activity_days | Days since last meaningful activity | Number | Current |
ootb_last_activity_date | Date of last activity | Date | Current |
ootb_response_rate | Email response rate percentage | Number | last_30_days, current_quarter |
Account Pipeline Metrics
Metric Slug | Description | Data Type | Variations |
ootb_total_pipeline_value | Total value of all opportunities | Number | Current |
ootb_open_pipeline_value | Value of open opportunities | Number | Current |
ootb_won_pipeline_value | Value of won opportunities | Number | current_quarter, current_year, last_quarter |
ootb_lost_pipeline_value | Value of lost opportunities | Number | current_quarter, current_year, last_quarter |
ootb_opportunity_count | Number of opportunities | Number | total, open, won, lost |
ootb_average_deal_size | Average opportunity value | Number | Current |
Account Engagement Trends
Metric Slug | Description | Data Type | Variations |
ootb_engagement_trend | Direction of engagement | String | Values: increasing, stable, declining |
ootb_activity_frequency | Activity frequency trend | String | Values: high, medium, low |
ootb_multi_threading_score | Number of contacts engaged | Number | Current |
ootb_executive_engagement | C-level contact engagement | Boolean | Current |
Opportunity Object
Opportunity-level metrics focus on individual deal progression, velocity, and conversion likelihood.
Core Opportunity Fields
Field Name | Description | Data Type | Example Value |
crm_opportunity_id | Unique CRM opportunity identifier | String | "0061234567890CD" |
crm_opportunity_name | Opportunity name | String | "Acme - Q4 License Renewal" |
crm_account_id | Associated account ID | String | "0011234567890AB" |
crm_account_name | Associated account name | String | "Acme Corporation" |
opportunity_owner | Opportunity owner name | String | "Jane Doe" |
opportunity_value | Deal value/amount | Number | 125000 |
expected_close_date | Forecasted close date | Date | "2024-12-31" |
actual_close_date | Actual close date (if closed) | Date | "2024-11-15" |
Opportunity Stage & Status
Metric Slug | Description | Data Type | Example Values |
ootb_opportunity_stage | Current sales stage | String | "Proposal", "Negotiation", "Closed Won" |
ootb_stage_probability | Win probability % | Number | 75 |
ootb_days_in_current_stage | Days in current stage | Number | 14 |
ootb_total_sales_cycle_days | Total days in sales cycle | Number | 89 |
ootb_stage_progression_velocity | Stage change frequency | Number | 0.8 |
Opportunity Scoring & Prediction
Metric Slug | Description | Data Type | Range |
ootb_win_probability_score | AI-predicted win likelihood | Number | 0-100 |
ootb_deal_velocity_score | Deal progression speed | Number | 0-100 |
ootb_competition_risk_score | Competitive threat level | Number | 0-100 |
ootb_budget_confirmed_score | Budget qualification score | Number | 0-100 |
Opportunity Activity
Metric Slug | Description | Data Type | Variations |
ootb_emails_sent_opp | Emails sent for this opportunity | Number | total, last_30_days |
ootb_meetings_held_opp | Meetings held for this opportunity | Number | total, last_30_days |
ootb_last_meaningful_activity_date | Date of last significant activity | Date | Current |
ootb_stakeholder_engagement_count | Number of stakeholders contacted | Number | Current |
ootb_champion_identified | Champion contact identified | Boolean | Current |
User Object
User-level metrics track individual and team performance across activities, pipeline, and results.
Core User Fields
Field Name | Description | Data Type | Example Value |
crm_user_id | Unique CRM user identifier | String | "0051234567890EF" |
user_name | Full name | String | "John Smith" |
user_email | Email address | String | |
user_role | Job title/role | String | "Account Executive" |
team_name | Team assignment | String | "Enterprise Sales" |
manager_name | Direct manager | String | "Sarah Johnson" |
hire_date | Employee start date | Date | "2023-01-15" |
User Activity Metrics
Metric Slug | Description | Data Type | Variations |
ootb_emails_sent_user | Total emails sent by user | Number | daily, weekly, monthly, quarterly |
ootb_emails_received_user | Total emails received by user | Number | daily, weekly, monthly, quarterly |
ootb_meetings_booked | Meetings booked by user | Number | weekly, monthly, quarterly |
ootb_calls_made_user | Calls made by user | Number | daily, weekly, monthly |
ootb_activities_logged | Total CRM activities logged | Number | weekly, monthly, quarterly |
User Performance Metrics
Metric Slug | Description | Data Type | Variations |
ootb_pipeline_generated | Pipeline value generated | Number | monthly, quarterly, yearly |
ootb_opportunities_created | New opportunities created | Number | monthly, quarterly, yearly |
ootb_deals_won | Opportunities won | Number | monthly, quarterly, yearly |
ootb_revenue_generated | Revenue closed | Number | monthly, quarterly, yearly |
ootb_quota_attainment | Quota achievement percentage | Number | monthly, quarterly, yearly |
ootb_win_rate | Win rate percentage | Number | quarterly, yearly |
User Engagement Metrics
Metric Slug | Description | Data Type | Variations |
ootb_response_rate_user | Email response rate | Number | monthly, quarterly |
ootb_meeting_acceptance_rate | Meeting acceptance rate | Number | monthly, quarterly |
ootb_account_penetration | Accounts actively engaged | Number | monthly, quarterly |
ootb_new_contact_creation | New contacts added | Number | monthly, quarterly |
Custom Metrics
In addition to out-of-the-box metrics, the Query API provides access to organization-specific metrics created in your Backstory instance.
Finding Custom Metric Slugs
Custom metrics follow these naming patterns:
Custom Account Metrics: custom_account_{metric_name}
Custom Opportunity Metrics: custom_opportunity_{metric_name}
Custom User Metrics: custom_user_{metric_name}
Derived Metrics: derived_{object}_{metric_name}
Common Custom Metric Examples
Type | Example Slug | Description |
Account | custom_account_nps_score | Account Net Promoter Score |
Account | custom_account_product_usage | Product usage intensity |
Opportunity | custom_opportunity_technical_score | Technical fit assessment |
Opportunity | custom_opportunity_legal_approval | Legal approval status |
User | custom_user_territory_coverage | Territory coverage percentage |
User | custom_user_specialization_score | Product specialization level |
Discovering Available Metrics
To find all available metrics in your instance:
Contact Your Backstory Administrator - They can provide a complete list of configured metrics
Use the Backstory Web Interface - Browse Reports → Metrics Library
API Discovery Query - Contact Backstory support for a discovery endpoint (coming in future releases)
Metric Variations
Many metrics support time-based variations to provide historical and period-specific data.
Remember: When using variations, the variation_id must be the full slug + time period (e.g., "ootb_emails_sent_last_30_days"), not just the time period alone.
Common Variation IDs
Variation ID | Description | Applicable Objects |
current | Current/latest value | All objects |
last_7_days | Rolling 7-day period | Account, User |
last_30_days | Rolling 30-day period | Account, User |
last_90_days | Rolling 90-day period | Account, User |
current_week | Current calendar week | User |
current_month | Current calendar month | All objects |
current_quarter | Current fiscal quarter | All objects |
current_year | Current fiscal year | All objects |
last_month | Previous calendar month | All objects |
last_quarter | Previous fiscal quarter | All objects |
last_year | Previous fiscal year | All objects |
Using Variations in Queries
{
"columns": [
{
"slug": "ootb_emails_sent",
"variation_id": "ootb_emails_sent_current_quarter"
},
{
"slug": "ootb_meetings_booked",
"variation_id": "ootb_meetings_booked_last_30_days"
}
]
}
Data Types & Formats
Supported Data Types
Data Type | Description | Example Values | Notes |
String | Text values | "Technology", "John Smith" | Use quotes in filters |
Number | Numeric values | 42, 1250.50, 0 | No quotes in filters |
Boolean | True/false values | true, false | Lowercase, no quotes |
Date | Date values | "2024-01-15" | ISO format (YYYY-MM-DD) |
Array | List of values | ["Value1", "Value2"] | Used with $in/$nin operators |
Special Value Handling
Null Values: Use {"$exists": false} to filter for missing values
Empty Strings: Use {"$eq": ""} to filter for empty text fields
Zero Values: Use {"$eq": 0} to filter for zero numeric values
Best Practices
Metric Selection
Request Only Needed Metrics: Minimize API response size and processing time
Use Appropriate Variations: Select the right time period for your analysis
Combine Related Metrics: Group logically related metrics in single queries
Performance Optimization
Filter Early: Apply restrictive filters to reduce data volume
Index-Friendly Sorts: Sort by CRM IDs when possible for better performance
Batch Related Queries: Combine related data requests when feasible
Data Quality
Validate Metric Slugs: Ensure all referenced metrics exist in your instance
Handle Missing Data: Account for null/empty values in your data processing
Understand Metric Definitions: Verify metric calculations match your expectations
For query syntax and filtering examples, see the Query Language Reference page.
Need Help?
Contact your CSM or email support@backstory.ai.