Skip to main content
POST
/
api
/
investigate
{
  "synthesis": "Energy costs have risen 8.2% over the past 12 weeks...",
  "implication": "Low-income discretionary spend is likely to contract further in Q2...",
  "question": "How are rising energy costs affecting low-income consumer spending?",
  "geo": "US",
  "sources": ["CPI Energy Sub-Index", "Income-Stratified Spending", "Macro Indicators"]
}

​
Authentication

Requires a valid JWT token in the Authorization header. 
Authorization: Bearer <your-jwt-token>

​
Rate Limits

10 requests per 60-second window per authenticated user.

​
Request Body

​
question
string
required
The research question to investigate. Maximum 500 characters.
​
geo
string
Geographic scope. One of US or UK.
​
weeks
number
default:"12"
Lookback window in weeks. Range: 1—104.
​
cpix_score
number
Optional CPIX composite score to provide additional context.
​
drivers
array
Array of driver objects to seed the analysis.
​
signals
array
Array of signal objects to incorporate.
​
clientProfile
string
Optional client context for tailored analysis. Maximum 500 characters.

​
Response

​
synthesis
string
AI-generated narrative synthesising the available data and signals.
​
implication
string
Actionable implication derived from the synthesis.
​
question
string
The original question echoed back.
​
geo
string
Geographic scope used for the analysis.
​
sources
array
List of data sources referenced in the synthesis.
cURL
curl -X POST "https://api.consumersignals.io/api/investigate" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How are rising energy costs affecting low-income consumer spending?",
    "geo": "US",
    "weeks": 12
  }'
Python
import requests

response = requests.post(
    "https://api.consumersignals.io/api/investigate",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json"
    },
    json={
        "question": "How are rising energy costs affecting low-income consumer spending?",
        "geo": "US",
        "weeks": 12
    }
)
data = response.json()
TypeScript
const response = await fetch(
  "https://api.consumersignals.io/api/investigate",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_JWT_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      question: "How are rising energy costs affecting low-income consumer spending?",
      geo: "US",
      weeks: 12,
    }),
  }
);
const data = await response.json();

{
  "synthesis": "Energy costs have risen 8.2% over the past 12 weeks...",
  "implication": "Low-income discretionary spend is likely to contract further in Q2...",
  "question": "How are rising energy costs affecting low-income consumer spending?",
  "geo": "US",
  "sources": ["CPI Energy Sub-Index", "Income-Stratified Spending", "Macro Indicators"]
}