Rezolve LabsDocs
Sign in
Documentation menu

AEO runs and results

Create a project, a flow and a run, wait for the run to finish, then read its results with the flow_id and run_id.

AEO (answer-engine optimisation) measures how AI assistants answer questions about your brand. You get results in a fixed order:

  1. Create a project.
  2. Create a flow in that project.
  3. Start a run of the flow.
  4. Poll the run until its status is completed.
  5. Read the results, passing the flow_id and the run_id.

All paths below are under https://api.rezolvelabs.com/api/v1 and take your key in X-API-KEY.

1. Create a project

POST /aeo/projects creates one. GET /aeo/projects lists the ones you have. Keep the project's id: it is the project_id of the next step.

2. Create a flow

A flow is the set of questions and brands a run checks. It needs a project_id.

  • POST /aeo/flows creates a flow in a project.
  • POST /aeo/flows/scaffold builds a complete flow in one call. It needs project_id, name and brand.

GET /aeo/flows?project_id=<id> lists a project's flows. Keep the flow's id: it is the flow_id of every later step.

3. Start a run

POST /aeo/runs starts one. The body needs flow_id and models (the list from GET /aeo/available-models). The request also needs an Idempotency-Key header: any unique value, such as a UUID. If the request fails and you retry it, send the same value, so the run doesn't start twice.

bash
curl -X POST "https://api.rezolvelabs.com/api/v1/aeo/runs" \
  -H "X-API-KEY: $RZLV_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"flow_id": "<flow_id>", "models": ["<model id>"]}'

The answer holds the run_id. To see what a run will cost first, call POST /aeo/estimation/run.

4. Poll the run

GET /aeo/runs/{run_id} shows the run's status and progress. Ask again until status is completed. The other statuses are pending, in_progress, failed, cancelled and paused.

Leave a few seconds between polls. Each poll counts against your plan's per-minute limit.

5. Read the results

Read the results once the run is completed. A run's results need both the flow_id and the run_id as query parameters, not just the run_id:

bash
curl "https://api.rezolvelabs.com/api/v1/aeo/results/share-of-answers?flow_id=<flow_id>&run_id=<run_id>" \
  -H "X-API-KEY: $RZLV_KEY"

A call that leaves one out is refused with 422, naming the missing parameter (for example flow_id: Field required).

ResultsRequired query parameters
share-of-answers, share-of-brand-mentions, share-of-unique-brand-mentions, mentions, average-rank, foundational-metrics, sentimentflow_id, run_id
citations, citations/summary, citations/domains, citations-by-domain, top-domains, share-of-source-citations, domain-entity-linksflow_id, run_id
questionrun_id, question_id
The trends (paths ending in -trend)flow_id and a date range, start_date and end_date (YYYY-MM-DD), with no run_id. share-of-answers-trend and share-of-unique-brand-mentions-trend need both dates; the other trends accept them

Each path is under /aeo/results/, such as /aeo/results/citations/summary.

Filters such as tags, models, entities and entity_types are lists. Send a list by repeating the name: models=a&models=b.