Query API is Backstory's data export solution that lets you access all your metrics and export them as CSV files. You can filter data, specify time periods, and retrieve exactly the information you need for analysis. The API uses a simple JSON format to build queries and returns structured CSV data ready for use in spreadsheets or other tools.
What You Can Do
Export account, opportunity, or user data with custom filters to get specific subsets of your records
Access any metric including out-of-the-box metrics and your organization's custom KPIs
Specify time periods for activity metrics like meetings, emails, and calls
Download CSV files ready for immediate analysis
Getting Started
Prerequisites
Before you begin, make sure you have:
Admin access to Backstory to generate API credentials
A tool to make HTTP requests (like Postman, curl, or a programming language)
Basic familiarity with JSON format
Step 1: Generate API Credentials
Log into Backstory as an Admin user
Go to Settings > API Key Management
Click + Generate API Key
Copy your API Key (client_id) and API Secret (client_secret)
Store these credentials securely—never share them publicly
Step 2: Get Your Access Token
Exchange your credentials for an access token by making this request:
POST https://api.people.ai/v3/auth/tokens
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
client_id={your_api_key}
client_secret={your_api_secret}
You'll receive a response like this:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"token_type": "bearer",
"expires_in": 3600
}The access token expires after 1 hour, so you'll need to request a new one when it expires.
Step 3: Make Your First Query
Use your access token to export data. Here's a simple example that exports at-risk accounts:
POST https://api.people.ai/v3/beta/insights/export
Authorization: Bearer {access_token}
Content-Type: application/json
{
"object": "account",
"columns": [
{"slug": "ootb_account_crm_id"},
{"slug": "ootb_account_name"},
{"slug": "ootb_account_engagement_level"}
],
"filter": {
"attribute": {"slug": "ootb_account_engagement_level"},
"clause": {"$lte": 50}
},
"sort": [
{
"attribute": {"slug": "ootb_account_engagement_level"},
"direction": "asc"
}
]
This query returns accounts with a health score of 50 or lower, sorted from lowest to highest.
Building Your Queries
Choosing Your Data Object
Start by selecting which type of data you want to export:
account - Company-level data and health metrics
opportunity - Deal information and pipeline metrics
user - Sales rep activity and performance data
Selecting Columns
List the metrics you want to include in your export using their slug names:
"columns": [
{"slug": "ootb_account_crm_id"},
{"slug": "ootb_account_name"},
{"slug": "ootb_account_engagement_level"}
]
Note: See a list of all OOTB slugs in the Object & Metric Reference.
Adding Filters
Filter your data to return only the records you need. Use comparison operators like:
$eq - equals
$lte - less than or equal to
$gte - greater than or equal to
Example filter for accounts with health scores below 50:
"filter": {
"attribute": {"slug": "ootb_account_engagement_level"},
"clause": {"$lte": 50}
}
Sorting Results
Sort your data by one or more fields:
"sort": [
{
"attribute": {"slug": "ootb_account_engagement_level"},
"direction": "desc"
}
]
Use "asc" for ascending (lowest to highest) or "desc" for descending (highest to lowest).
Working with Time-Based Metrics
Many metrics track activity over time, like emails sent or meetings held. These require special syntax.
Understanding Time Periods
Time-based metrics use a variation_id that specifies the time range:
{
"slug": "ootb_user_external_meetings_matched",
"variation_id": "ootb_user_external_meetings_matched_last_30_days"
}The variation_id follows this pattern: {base_slug}_{time_period}
Available Time Periods
_last_7_days - Previous 7 days (this is the default if you don't specify)
_last_30_days - Previous 30 days
_last_90_days - Previous 90 days
_current_quarter - Current fiscal quarter
_last_quarter - Previous fiscal quarter
Not all metrics support all time periods. Check with your admin for available options.
Example: User Activity Export
Here's how to export user activity counts for the last 30 days:
{
"object": "user",
"columns": [
{"slug": "ootb_user"},
{"slug": "ootb_user_email"},
{
"slug": "ootb_user_external_meetings_matched",
"variation_id": "ootb_user_external_meetings_matched_last_30_days"
},
{
"slug": "ootb_user_count_emails_sent",
"variation_id": "ootb_user_count_emails_sent_last_30_days"
}
]
}
API Limitations and Guidelines
Rate Limits
10 API calls per day maximum - Plan your queries carefully to stay within this limit
~1.5 million records per hour - Processing speed for large exports
Data refreshes twice per business day - Account and opportunity data updates
Important Behaviors
Silent failures for invalid slugs: The API will not tell you if a metric slug is invalid. It simply omits that column from the results. Always check that your CSV headers match what you expected.
Default time periods: If you request a time-based metric without specifying a variation_id, you'll get the 7-day version automatically.
Best Practices
Use filters to reduce the size of your results and stay within limits
Cache or save your results to avoid making the same query multiple times
Combine related data in a single query when possible
Monitor your daily usage to ensure you don't exceed the 10-call limit
Data Freshness
Account and opportunity data: Updated twice daily
Activity data: Near real-time (updates within 1 hour)
Custom metrics: Depends on how your organization has configured them
Next Steps
🚀 Start Building: Review the Query Language Reference to understand query syntax.
📊 Explore Data: Check the Object & Metric Reference for available metrics.
💻 See Examples: Browse and run example requests in this Postman Collection.
🔧 Get Help: Use the Troubleshooting Guide if you encounter issues.
Frequently Asked Questions (FAQs)
What happens if I use an invalid metric slug?
The API won't return an error. It will simply omit that column from your CSV. Always verify your CSV headers match the columns you requested.
How long does my access token last?
Access tokens expire after 1 hour. You'll need to request a new token when yours expires.
What if I don't specify a time period for a time-based metric?
The API automatically returns the 7-day version of the metric by default.
Can I export custom metrics created by my organization?
Yes, the Query API supports all custom metrics. Use the same slug format as standard metrics.
How do I know which time periods are available for a metric?
Not all metrics support all time periods. Contact your Backstory administrator for the complete list of available variations for metrics in your instance.
What's the maximum number of records I can export?
There's no specific record limit, but the API processes approximately 1.5 million records per hour. Large exports may take time to complete.
Can I use AND/OR logic in my filters?
Yes, the Query API supports complex filtering with AND/OR logic and multiple comparison operators.
How often is my data updated?
Account and opportunity data refreshes twice per business day. Activity data (emails, meetings, calls) updates near real-time within 1 hour.
Need Help?
Contact your CSM or email support@backstory.ai.