POST registers the query and returns a request_id immediately; the query runs in the background; you then poll for status and fetch the results.
Endpoints
The Analytics Query APIs include the following endpoints:- Register a Behavior Query: Run a Behavior analysis.
- Register a Funnels Query: Run a Funnels analysis.
- Register a Retention Query: Run a Retention analysis.
- Register a Session-Source Query: Run a Session/Source analysis.
- Register a User Analysis Query: Run a User Property Analysis.
- Get Query Status: Check the execution status of a registered query.
- Get Query Results: Fetch the resolved results of a completed query.
Typical Workflow
Each analysis follows the same submit, poll, and fetch sequence:1
Submit the Query
Call one of the analysis endpoints, for example Register a Behavior Query. The response echoes the analysis
type and returns a request_id.2
Poll for Status
Call Get Query Status with that
request_id. The query is still running while status is PENDING or PROCESSING, so keep polling until it reaches a final status of SUCCESSFUL or FAILED. When a query fails, the response also returns a failure_reason.3
Fetch the Results
Call Get Query Results with the same
request_id to retrieve the results. The shape of the data array depends on the analysis type.FAQs
How long does a query take to complete?
How long does a query take to complete?
Completion time depends on the time range, the number of events, and the volume of data scanned. Poll Get Query Status until the status is
SUCCESSFUL, then fetch the results. Avoid polling in a tight loop; leave a short interval between calls.Can I re-run a query with the same request_id?
Can I re-run a query with the same request_id?
No. A
request_id identifies one query execution. To run the analysis again, register a new query and use the new request_id.Why did my query return 428?
Why did my query return 428?
A
428 means the workspace has reached its monthly Fair Usage Policy (FUP) limit for analytics usage. Analytics queries are blocked for the rest of the billing cycle. Contact your Customer Success Manager to expand your quota.Why does Get Query Results return different fields for different queries?
Why does Get Query Results return different fields for different queries?
The rows returned depend on the analysis type the query was registered for. Behavior, Funnels, Retention, Session/Source, and User Analysis each add their own fields on top of the common ones. Handle each row as a flexible set of keys. See Get Query Results for an example of each shape.
Why did my query fail validation with a 400?
Why did my query fail validation with a 400?
Each analysis enforces limits on how many events, segments, and breakdowns a single query can include. The error message names the field that failed. Check the description of that field on the endpoint page for its accepted values and limits.
Which data does the API return compared to the dashboard?
Which data does the API return compared to the dashboard?
These endpoints run the same analyses as the Analyze section of the MoEngage dashboard, scoped to the authenticated workspace. To read data from saved dashboard charts instead of running a new query, use the Custom Dashboards APIs.