Forecasting Query API allows you to retrieve forecast records across your organizational hierarchy and historical snapshots.
Note: The Forecasting API is currently in beta.
Authentication
Access to Backstory's APIs requires an API key. API keys can be generated by administrators through the API Key Management interface.
Getting an Access Token
Use your API credentials to request an access token:
curl -X POST https://api.people.ai/v3/auth/tokens \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=
{API_KEY}&client_secret={API_SECRET}"
You'll receive a response like this:
{
"access_token": "{access_token}",
"expires_in": 7200,
"expires_at": "2026-01-01T00:00:00.000000",
"token_type": "bearer"
}
The access token expires after 7200 seconds (2 hours). Include this token in the Authorization header for all API requests.
Query Endpoint
Retrieve forecast records with flexible filtering options across hierarchy nodes, time periods, and historical snapshots.
Request Parameters
Parameter | Type | Required | Description |
forecast_type_id | number | Yes | ID reference to the forecast type |
per_page | number | Yes | Number of records per page (min: 1, max: 1000) |
fiscal_period_id | string | No | ID reference to the fiscal period (defaults to current period) |
fiscal_period_external_id | string | No | Salesforce ID reference to the fiscal period. Use either this or fiscal_period_id, not both |
sort | string | No | Sort order: default (by node name, node ID, submitted by) or hierarchy_level (by level, name, ID, submitted by) |
hierarchy_node_id | number | No | ID reference to query a specific hierarchy node |
hierarchy_node_ownership_external_id | string | No | Salesforce ID reference to a hierarchy node. Use either this or hierarchy_node_id, not both |
include_descendants | boolean | No | When used with a hierarchy node parameter, includes all child nodes in results |
page | number | No | Page number for pagination (min: 1) |
timeframe | object | No | Filters for historical snapshots (defaults to latest snapshots only) |
timeframe.snapshots | string | Yes* | Snapshot type: latest or all (*required if timeframe is provided) |
timeframe.since | number | No | Unix timestamp in milliseconds for timeframe start |
timeframe.until | number | No | Unix timestamp in milliseconds for timeframe end |
Example Request
{
"forecast_type_id": 10089,
"per_page": 100,
"fiscal_period_external_id": "0261U000000WeG6RAD",
"sort": "hierarchy_level",
"hierarchy_node_ownership_external_id": "0MI6e00000030JYRAV",
"include_descendants": true,
"timeframe": {
"snapshots": "latest",
"since": 1765578693615
}
}
Response Format
Response Headers
Pagination information is provided in the response headers:
Header | Type | Description |
X-Total-Count | number | Total number of items across all pages |
X-Page-Last | number | Last page number |
X-Limit | number | Number of items per page |
X-Page | number | Current page number |
Response Body
The response returns a JSON array of forecast record snapshots. Each object contains:
Property | Type | Description |
cadence_period_id | string | ID of the cadence period when this record was submitted |
hierarchy_node_id | number | ID reference to the associated hierarchy node |
hierarchy_node_ownership_external_id | string | Salesforce ID reference of the hierarchy node |
hierarchy_node_name | string | Name of the hierarchy node |
submitted_by | number | Backstory user ID who last submitted this record (null if never submitted) |
submitted_at | number | Unix timestamp of last submission (null if never submitted) |
notes | string | Notes from the last submission (null if never submitted) |
fields | object | Forecast field values at the time of snapshot |
fields[<slug>].value | number | Value for each configured forecast field |
Example Response
[
{
"hierarchy_node_id": 10053,
"hierarchy_node_ownership_external_id": "0MIRi0000000H5tORC",
"hierarchy_node_name": "Jerri Gail",
"cadence_period_id": "e468a572-ba0f-7786-8560-d07234b1489",
"submitted_by": 400932,
"submitted_at": 1767082571417,
"notes": "Orbis - 15k",
"fields": {
"quota": {
"value": 100000.0
},
"gap_to_quota": {
"value": 68943.0
},
"forecast_call": {
"value": 42264.0
},
"closed_won": {
"value": 31057.0
},
"commit": {
"value": 42264.0
},
"best_case": {
"value": 131395.0
},
"open_pipeline": {
"value": 213998.0
}
}
}
]
Common Use Cases
Retrieve the latest forecast for all nodes in a fiscal period:
{
"forecast_type_id": 10089,
"per_page": 1000,
"fiscal_period_external_id": "0261U000000WeG6RAD"
}
Get historical snapshots for a specific hierarchy and descendants:
{
"forecast_type_id": 10089,
"per_page": 100,
"hierarchy_node_id": 5001,
"include_descendants": true,
"timeframe": {
"snapshots": "all",
"since": 1704067200000,
"until": 1735689600000
}
}
Need Help?
Reach out to your CSM or email support@backstory.ai.