Analyzing Prompts

In this guide we'll cover how to fetch AI Visibility metrics for your GenAI Lens prompts using the analytics API. You'll learn how to fetch:

Aggregate metrics - the total for one or more metrics across a time period
Date histograms - metrics broken down into time buckets, to see trends over time
Top terms - metrics broken down by a dimension, for example by organization, brand, or person

All three use the same endpoint and request structure, varying only the analysis block.

Try it in the console

You can build and run these analytics calls interactively - without writing any code - in the V4 Analytics Console. Select your prompts, configure an analysis, and run it or copy the equivalent cURL.

Before you start

To run through this guide you will need:

Your Meltwater API token
One or more prompt IDs, or a prompt folder ID - see Fetching Prompts

Analysis requests

All AI Visibility analytics requests are made to the POST /analytics/analyze endpoint with provider set to llm.

Here's a minimal request which we'll break down below:

curl --request POST \
  --url "https://api.meltwater.com/v4/analytics/analyze" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "apikey: **********" \
  --data '{
  "provider": "llm",
  "tz": "UTC",
  "period": {
    "start": "2026-05-01T00:00:00",
    "end": "2026-05-08T00:00:00"
  },
  "query": {
    "prompts": {
      "all": ["69f26ff5ffe10bbbaccc0c234"]
    }
  },
  "analysis": {
    "type": "metrics",
    "metrics": ["mentions"]
  }
}'

Every request has five required parts: provider, tz, period, query, and analysis.

Provider

For AI Visibility, always set provider to llm.

Time period

Specify the time window to analyse in the period object:

start and end - the period you'd like to analyse (ISO 8601 timestamps, excluding timezone/offset). The result is inclusive of start and exclusive of end.
tz (top-level) - an identifier from the IANA database, for example UTC or America/New_York.

Query

The query object selects which prompts to analyse. You can select prompts directly, or select every prompt in one or more folders.

To select prompts directly, use the query.prompts field with prompt IDs:

all - the analysis covers every selected prompt
any - the analysis covers any of the selected prompts
none - exclude these prompts

"query": {
  "prompts": {
    "all": ["69f26ff25ac999d02590b35e", "69f26ff25ac999d02590b35c"]
  }
}

To select prompts by the folder they belong to, use query.prompt_folders with folder IDs instead:

"query": {
  "prompt_folders": {
    "all": ["69f26fe52e166c14939981ae"]
  }
}

You must supply at least one ID in all or any, in either prompts or prompt_folders. If you combine both, prompts must match both conditions.

Analysis

The analysis block defines what to calculate. The sections below cover the three analysis types supported for AI Visibility.

Metrics and dimensions

Examples below use metrics such as mentions and visibility, and dimensions such as organizations and people. For the full list of metrics and dimensions supported for AI Visibility, see the AI Visibility analytics options reference.

Aggregate metrics

To fetch the total (sum) for one or more metrics across the whole period, use the metrics analysis type and list the metrics you want:

{
  "provider": "llm",
  "tz": "UTC",
  "period": { "start": "2026-06-01T00:00:00", "end": "2026-06-08T00:00:00" },
  "query": {
    "prompts": {
      "any": [
        "69f26ff5ffe10bbbaccc0cc3",
        "69f26ff55ac999d02590b360",
        "69f26ff382b4668003a5c832",
        "69f26ff3aa04ce70bb7c648c",
        "69f26ff398451b7f4644b10c"
      ]
    }
  },
  "analysis": {
    "type": "metrics",
    "metrics": ["mentions", "visibility"]
  }
}

The response echoes back your request and adds a result object. For a metrics analysis, result.analysis maps each requested metric to its total across the selected prompts and period:

{
  "provider": "llm",
  "tz": "UTC",
  "period": { "start": "2026-06-01T00:00:00", "end": "2026-06-08T00:00:00" },
  "query": { "prompts": { "any": ["69f26ff5ffe10bbbaccc0cc3", "69f26ff55ac999d02590b360", "69f26ff382b4668003a5c832", "69f26ff3aa04ce70bb7c648c", "69f26ff398451b7f4644b10c"] } },
  "analysis": { "type": "metrics", "metrics": ["mentions", "visibility"] },
  "result": {
    "analysis": {
      "mentions": 6440,
      "visibility": 48
    }
  }
}

Use this to answer questions like "how many times was my brand mentioned across these prompts this period?".

Date histograms with metrics

To see how metrics change over time, use the date_histogram analysis type and nest a metrics analysis inside it. The histogram splits the period into buckets, and the nested analysis is calculated for each bucket.

granularity - the bucket size: day, week, or month

{
  "provider": "llm",
  "tz": "UTC",
  "period": { "start": "2026-06-01T00:00:00", "end": "2026-06-08T00:00:00" },
  "query": {
    "prompts": {
      "any": [
        "69f26ff5ffe10bbbaccc0cc3",
        "69f26ff55ac999d02590b360",
        "69f26ff382b4668003a5c832",
        "69f26ff3aa04ce70bb7c648c",
        "69f26ff398451b7f4644b10c"
      ]
    }
  },
  "analysis": {
    "type": "date_histogram",
    "granularity": "day",
    "analysis": {
      "type": "metrics",
      "metrics": ["mentions", "visibility"]
    }
  }
}

For a date_histogram, result.analysis is an array of buckets. Each bucket has a key (the start of the time bucket) and an analysis object holding the nested metrics for that bucket. The request echo is omitted below for brevity:

{
  "result": {
    "analysis": [
      { "key": "2026-06-01T00:00:00", "analysis": { "mentions": 86, "visibility": 66 } },
      { "key": "2026-06-02T00:00:00", "analysis": { "mentions": 145, "visibility": 48.5 } },
      { "key": "2026-06-03T00:00:00", "analysis": { "mentions": 97, "visibility": 69 } },
      { "key": "2026-06-04T00:00:00", "analysis": { "mentions": 79, "visibility": 64 } },
      { "key": "2026-06-05T00:00:00", "analysis": { "mentions": 131, "visibility": 49.5 } },
      { "key": "2026-06-06T00:00:00", "analysis": { "mentions": 95, "visibility": 67 } },
      { "key": "2026-06-07T00:00:00", "analysis": { "mentions": 84, "visibility": 67 } },
      { "key": "2026-06-08T00:00:00", "analysis": { "mentions": 120, "visibility": 47.5 } }
    ]
  }
}

This returns the requested metrics for each time bucket - here, daily mentions and visibility across the week - which you can plot as a trend line. Note that visibility can be fractional (for example 48.5), whereas mentions is a whole count.

Top terms with metrics

To break metrics down by a dimension - for example, to see which organizations are mentioned most across your prompts - use the top_terms analysis type. Like date_histogram, it wraps a nested analysis block that defines the metrics to calculate for each term:

dimension - the dimension to group terms by, for example organizations, brands, or people
limit (optional) - the number of terms to return (default 10, max 100)
analysis (nested) - the metrics analysis to calculate for each term, using the same shape as Aggregate metrics

{
  "provider": "llm",
  "tz": "UTC",
  "period": { "start": "2026-06-01T00:00:00", "end": "2026-06-08T00:00:00" },
  "query": {
    "prompts": {
      "any": [
        "69f26ff5ffe10bbbaccc0cc3",
        "69f26ff55ac999d02590b360",
        "69f26ff382b4668003a5c832",
        "69f26ff3aa04ce70bb7c648c",
        "69f26ff398451b7f4644b10c"
      ]
    }
  },
  "analysis": {
    "type": "top_terms",
    "dimension": "organizations",
    "analysis": {
      "type": "metrics",
      "metrics": ["mentions", "visibility"]
    }
  }
}

For a top_terms analysis, result.analysis is an array of terms. Each term has a key (the term itself) and an analysis object holding its metrics. The request echo is omitted below for brevity:

{
  "result": {
    "analysis": [
      { "key": "Anthropic", "analysis": { "mentions": 1852, "visibility": 89 } },
      { "key": "OpenAI", "analysis": { "mentions": 1820, "visibility": 89 } },
      { "key": "Microsoft", "analysis": { "mentions": 120, "visibility": 21 } },
      { "key": "Google", "analysis": { "mentions": 55, "visibility": 12 } },
      { "key": "IntuitionLabs", "analysis": { "mentions": 46, "visibility": 13 } },
      { "key": "Meta", "analysis": { "mentions": 34, "visibility": 11 } },
      { "key": "SaferAI", "analysis": { "mentions": 30, "visibility": 8 } },
      { "key": "Google DeepMind", "analysis": { "mentions": 27, "visibility": 10 } },
      { "key": "IBM", "analysis": { "mentions": 25, "visibility": 8 } },
      { "key": "NIST", "analysis": { "mentions": 23, "visibility": 9 } }
    ]
  }
}

Terms are returned in descending order of relevance, so the most-mentioned organizations appear first. This is the basis for share of voice: comparing your brand's metrics against the competitors surfaced alongside it in the same AI answers.

Before you start​

Analysis requests​

Provider​

Time period​

Query​

Analysis​

Aggregate metrics​

Date histograms with metrics​

Top terms with metrics​