> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics Query APIs Overview

> Run MoEngage Analytics queries — Behavior, Funnels, Retention, Session/Source, and User Property Analysis — and fetch their results programmatically.

The Analytics Query APIs let you run MoEngage's analysis queries programmatically and retrieve their results. They cover the same analyses available in the MoEngage dashboard: Behavior, Funnels, Retention, Session/Source (BFRS), and User Property Analysis (UPA).

These queries are asynchronous. A `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](/docs/api/analytics-queries/register-a-behavior-query): Run a Behavior analysis.
* [Register a Funnels Query](/docs/api/analytics-queries/register-a-funnels-query): Run a Funnels analysis.
* [Register a Retention Query](/docs/api/analytics-queries/register-a-retention-query): Run a Retention analysis.
* [Register a Session-Source Query](/docs/api/analytics-queries/register-a-session-source-query): Run a Session/Source analysis.
* [Register a User Analysis Query](/docs/api/analytics-queries/register-a-user-analysis-query): Run a User Property Analysis.
* [Get Query Status](/docs/api/analytics-queries/get-query-status): Check the execution status of a registered query.
* [Get Query Results](/docs/api/analytics-queries/get-query-results): Fetch the resolved results of a completed query.

## Typical Workflow

Each analysis follows the same submit, poll, and fetch sequence:

<Steps>
  <Step title="Submit the Query">
    Call one of the analysis endpoints, for example [Register a Behavior Query](/docs/api/analytics-queries/register-a-behavior-query). The response echoes the analysis `type` and returns a `request_id`.
  </Step>

  <Step title="Poll for Status">
    Call [Get Query Status](/docs/api/analytics-queries/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`.
  </Step>

  <Step title="Fetch the Results">
    Call [Get Query Results](/docs/api/analytics-queries/get-query-results) with the same `request_id` to retrieve the results. The shape of the `data` array depends on the analysis type.
  </Step>
</Steps>

## FAQs

<AccordionGroup>
  <Accordion title="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](/docs/api/analytics-queries/get-query-status) until the status is `SUCCESSFUL`, then fetch the results. Avoid polling in a tight loop; leave a short interval between calls.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/docs/api/analytics-queries/get-query-results) for an example of each shape.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/docs/api/analytics/analytics-overview).
  </Accordion>
</AccordionGroup>

## Postman Collection

Test these endpoints quickly using our pre-configured Postman collection: [View MoEngage Analytics Query APIs Collection](https://www.postman.com/moengage-dev/api-docs/collection/xk31arr/moengage-analytics-query-api-s).