API Evangelist conversational phrasing for Analytics API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Analytics API
  version: 1.0.0
extends: openapi/algolia-analytics-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 30
- target: $.paths['/{path}'].get
  update:
    x-apievangelist-phrasing:
      intent: Send a custom GET request to the Analytics API
      effect: read
      questions:
      - Can I call an Analytics API endpoint the client library doesn't wrap yet with a raw GET?
      - Is there a generic way to read from an arbitrary Analytics API path?
      instructions:
      - text: Send a raw GET request to the Analytics API path {path}.
        slots:
          path: path.path
      - text: Call GET on Analytics endpoint {path} with query parameters {parameters}.
        slots:
          path: path.path
          parameters: query.parameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{path}'].put
  update:
    x-apievangelist-phrasing:
      intent: Send a custom PUT request to the Analytics API
      effect: write
      questions:
      - How can I send a PUT to an Analytics API path that has no dedicated method?
      - Can I replace something at a custom Analytics endpoint using a raw PUT call?
      instructions:
      - text: Send a raw PUT request to the Analytics API path {path}.
        slots:
          path: path.path
      - text: Issue a PUT to Analytics endpoint {path} with query parameters {parameters}.
        slots:
          path: path.path
          parameters: query.parameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{path}'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a custom POST request to the Analytics API
      effect: write
      questions:
      - What's the way to POST to a new Analytics API endpoint before the SDK supports it?
      - Can I make a raw POST call to any Analytics path?
      instructions:
      - text: Send a raw POST request to the Analytics API path {path}.
        slots:
          path: path.path
      - text: POST to Analytics endpoint {path} passing query parameters {parameters}.
        slots:
          path: path.path
          parameters: query.parameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{path}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Send a custom DELETE request to the Analytics API
      effect: destructive
      questions:
      - How do I send a raw DELETE to an Analytics API path the client doesn't cover?
      - Can I call DELETE on an arbitrary Analytics endpoint?
      instructions:
      - text: Send a raw DELETE request to the Analytics API path {path}.
        slots:
          path: path.path
      - text: Issue a DELETE against Analytics endpoint {path} with query parameters {parameters}.
        slots:
          path: path.path
          parameters: query.parameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/searches'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the most popular search queries
      effect: read
      questions:
      - What are people searching for most on my site?
      - Can I rank my top searches by click-through or revenue?
      - Which queries were most popular last month on my index?
      instructions:
      - text: Show the top searches on index {index}.
        slots:
          index: query.index
      - text: List the {limit} most popular queries on {index} from {startDate} to {endDate}.
        slots:
          limit: query.limit
          index: query.index
          startDate: query.startDate
          endDate: query.endDate
      - text: Rank top searches on {index} by {orderBy} including click analytics.
        slots:
          index: query.index
          orderBy: query.orderBy
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/searches/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count searches over a period
      effect: read
      questions:
      - How many searches did my index get each day this week?
      - What's the total search volume for a date range?
      instructions:
      - text: Count the searches on index {index}.
        slots:
          index: query.index
      - text: Give me the daily search count for {index} between {startDate} and {endDate}.
        slots:
          index: query.index
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/searches/noResults'].get
  update:
    x-apievangelist-phrasing:
      intent: List frequent searches that returned no results
      effect: read
      questions:
      - Which queries are coming back empty for my users?
      - What are shoppers searching for that I don't carry?
      instructions:
      - text: List the most frequent zero-result searches on {index}.
        slots:
          index: query.index
      - text: Show the top {limit} searches with no results on {index} since {startDate}.
        slots:
          limit: query.limit
          index: query.index
          startDate: query.startDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/searches/noClicks'].get
  update:
    x-apievangelist-phrasing:
      intent: List popular searches that got no clicks
      effect: read
      questions:
      - Which searches return results that nobody clicks?
      - Where are my search results failing to engage users?
      instructions:
      - text: List top searches without clicks on index {index}.
        slots:
          index: query.index
      - text: Show {limit} popular queries on {index} that led to no clicks between {startDate} and {endDate}.
        slots:
          limit: query.limit
          index: query.index
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/searches/noResultRate'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the share of searches with no results
      effect: read
      questions:
      - What percentage of my searches return zero results?
      - Is my no-results rate getting better day over day?
      instructions:
      - text: Get the no-results rate for index {index}.
        slots:
          index: query.index
      - text: Show the daily zero-result rate on {index} from {startDate} to {endDate}.
        slots:
          index: query.index
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/searches/noClickRate'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the share of searches with no clicks
      effect: read
      questions:
      - What fraction of tracked searches end without a click?
      - How has my no-click rate trended this month?
      instructions:
      - text: Get the no-click rate for index {index}.
        slots:
          index: query.index
      - text: Show the daily no-click rate on {index} between {startDate} and {endDate}.
        slots:
          index: query.index
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/hits'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the most frequently returned search results
      effect: read
      questions:
      - Which records show up most often in my search results?
      - What items appear most for a particular query?
      instructions:
      - text: List the top search results (hits) on index {index}.
        slots:
          index: query.index
      - text: Show the most frequent hits on {index} for the query {search}.
        slots:
          index: query.index
          search: query.search
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count unique search users
      effect: read
      questions:
      - How many unique users searched my site this week?
      - What's the daily breakdown of distinct searchers?
      instructions:
      - text: Count unique users searching index {index}.
        slots:
          index: query.index
      - text: Show daily unique searchers on {index} from {startDate} to {endDate}.
        slots:
          index: query.index
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/filters'].get
  update:
    x-apievangelist-phrasing:
      intent: List the most used filter attributes
      effect: read
      questions:
      - Which facets do my users filter by most?
      - What filter attributes are most common for a specific query?
      instructions:
      - text: List the top filter attributes used on index {index}.
        slots:
          index: query.index
      - text: Show which facets people filter by most on {index} when searching {search}.
        slots:
          index: query.index
          search: query.search
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/filters/{attribute}'].get
  update:
    x-apievangelist-phrasing:
      intent: List the most used values for one filter
      effect: read
      questions:
      - Which brands or colors do users pick most when filtering?
      - What are the most popular values for a given facet?
      instructions:
      - text: Show the top filter values for attribute {attribute} on index {index}.
        slots:
          attribute: path.attribute
          index: query.index
      - text: List the {limit} most selected {attribute} values on {index}.
        slots:
          limit: query.limit
          attribute: path.attribute
          index: query.index
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/filters/noResults'].get
  update:
    x-apievangelist-phrasing:
      intent: List filters used in searches with no results
      effect: read
      questions:
      - Which filter combinations lead users to empty result pages?
      - Are certain facet filters causing zero-result searches?
      instructions:
      - text: List the top filters used in no-result searches on index {index}.
        slots:
          index: query.index
      - text: Show filters applied to zero-result searches for {search} on {index}.
        slots:
          search: query.search
          index: query.index
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/countries'].get
  update:
    x-apievangelist-phrasing:
      intent: List the countries with the most searches
      effect: read
      questions:
      - Where in the world are my searches coming from?
      - Which countries search my index the most?
      instructions:
      - text: List the top countries by searches on index {index}.
        slots:
          index: query.index
      - text: Show the {limit} countries with the most searches on {index} since {startDate}.
        slots:
          limit: query.limit
          index: query.index
          startDate: query.startDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/clicks/averageClickPosition'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the average position of clicked results
      effect: read
      questions:
      - On average, how far down the results do users click?
      - Is my average click position improving after relevance changes?
      instructions:
      - text: Get the average click position for index {index}.
        slots:
          index: query.index
      - text: Show the daily average click position on {index} from {startDate} to {endDate}.
        slots:
          index: query.index
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/clicks/positions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get click counts by result position
      effect: read
      questions:
      - How many clicks does the first result get compared to the tenth?
      - What's the click distribution across result positions?
      instructions:
      - text: Show clicks per result position on index {index}.
        slots:
          index: query.index
      - text: Break down clicks by position for {index} between {startDate} and {endDate}.
        slots:
          index: query.index
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/clicks/clickThroughRate'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the search click-through rate
      effect: read
      questions:
      - What's the click-through rate on my search results?
      - Why is my CTR null instead of zero on some days?
      instructions:
      - text: Get the click-through rate for index {index}.
        slots:
          index: query.index
      - text: Show the daily CTR on {index} from {startDate} to {endDate}.
        slots:
          index: query.index
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/conversions/conversionRate'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the search conversion rate
      effect: read
      questions:
      - What share of tracked searches lead to a conversion?
      - How is my search conversion rate trending day by day?
      instructions:
      - text: Get the conversion rate for index {index}.
        slots:
          index: query.index
      - text: Show the daily conversion rate on {index} between {startDate} and {endDate}.
        slots:
          index: query.index
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/conversions/addToCartRate'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the add-to-cart rate from search
      effect: read
      questions:
      - How often do searches result in an item being added to the cart?
      - Which days had the best add-to-cart rate from search?
      instructions:
      - text: Get the add-to-cart rate for index {index}.
        slots:
          index: query.index
      - text: Show daily add-to-cart rates on {index} from {startDate} to {endDate}.
        slots:
          index: query.index
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/conversions/purchaseRate'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the purchase rate from search
      effect: read
      questions:
      - What percentage of searches end in a purchase?
      - Can I see the purchase rate per day for my store's search?
      instructions:
      - text: Get the purchase rate for index {index}.
        slots:
          index: query.index
      - text: Show daily purchase rates on {index} between {startDate} and {endDate}.
        slots:
          index: query.index
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/conversions/revenue'].get
  update:
    x-apievangelist-phrasing:
      intent: Get revenue attributed to search
      effect: read
      questions:
      - How much revenue does my search drive?
      - What's the average order value coming from search, and what do I need to send to see it?
      instructions:
      - text: Get search revenue metrics for index {index}.
        slots:
          index: query.index
      - text: Show total revenue and average order value from {index} for {startDate} to {endDate}.
        slots:
          index: query.index
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check when analytics were last updated
      effect: read
      questions:
      - How fresh is my analytics data?
      - Why is the analytics updated time null for a new index?
      instructions:
      - text: Check when analytics for index {index} were last updated.
        slots:
          index: query.index
      - text: Get the analytics update status of {index}.
        slots:
          index: query.index
      method: generated
      generated: '2026-09-26'
- target: $.paths['/3/patterns/fields'].get
  update:
    x-apievangelist-phrasing:
      intent: List the available analytics fields catalog
      effect: read
      questions:
      - Which metrics, filters and group-by fields can I use in analytics pattern queries?
      - What domain and field kind combinations are valid for the patterns endpoints?
      instructions:
      - text: Get the analytics field catalog.
      - text: List every metric, filter, group and distribution field available for pattern queries.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/3/patterns/timeseries'].post
  update:
    x-apievangelist-phrasing:
      intent: Query analytics metrics as a daily time series
      effect: read
      questions:
      - Can I chart a custom analytics metric per day, split by a grouping?
      - How do I get a per-day metric breakdown for each segment of my search traffic?
      instructions:
      - text: Get a daily time series of {metrics} with parameters {parameters}.
        slots:
          metrics: requestBody.metrics
          parameters: requestBody.parameters
      - text: Plot {metrics} over time on index {index}, one series per {groupBy}, using {parameters}.
        slots:
          metrics: requestBody.metrics
          index: query.index
          groupBy: requestBody.groupBy
          parameters: requestBody.parameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/3/patterns/scalar'].post
  update:
    x-apievangelist-phrasing:
      intent: Get single aggregate analytics totals
      effect: read
      questions:
      - How do I get one total number for a metric over a whole period?
      - Can I aggregate several analytics metrics into a single summary figure?
      instructions:
      - text: Compute period totals for {metrics} with parameters {parameters}.
        slots:
          metrics: requestBody.metrics
          parameters: requestBody.parameters
      - text: Give me a single aggregate of {metrics} on {index}, filtered by {filters}, using {parameters}.
        slots:
          metrics: requestBody.metrics
          index: query.index
          filters: requestBody.filters
          parameters: requestBody.parameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/3/patterns/table'].post
  update:
    x-apievangelist-phrasing:
      intent: Query analytics as a grouped, sorted table
      effect: read
      questions:
      - Can I build a table of analytics metrics grouped by a dimension and sorted?
      - Do I need an orderBy when grouping analytics rows?
      instructions:
      - text: Build a table of {metrics} grouped by {groupBy}, ordered by {orderBy}, with {parameters}.
        slots:
          metrics: requestBody.metrics
          groupBy: requestBody.groupBy
          orderBy: requestBody.orderBy
          parameters: requestBody.parameters
      - text: Return up to {limit} rows of {metrics} for index {index} using {parameters}.
        slots:
          limit: requestBody.limit
          metrics: requestBody.metrics
          index: query.index
          parameters: requestBody.parameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/3/patterns/distribution'].post
  update:
    x-apievangelist-phrasing:
      intent: Get histograms of numeric analytics fields
      effect: read
      questions:
      - How are values like hit counts distributed across my searches?
      - Can I bucket a numeric analytics field into a histogram?
      instructions:
      - text: Build histograms for {distributions} with parameters {parameters}.
        slots:
          distributions: requestBody.distributions
          parameters: requestBody.parameters
      - text: Bucket {distributions} into bins on index {index}, filtered by {filters}, using {parameters}.
        slots:
          distributions: requestBody.distributions
          index: query.index
          filters: requestBody.filters
          parameters: requestBody.parameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/setClientApiKey'].get
  update:
    x-apievangelist-phrasing:
      intent: Switch the API key the Analytics client uses
      effect: write
      questions:
      - Can I change which API key my Analytics client authenticates with?
      - Is it possible to rotate the key used for analytics reporting calls at runtime?
      instructions:
      - text: Switch the Analytics client to authenticate with API key {apiKey}.
        slots:
          apiKey: query.apiKey
      - text: Use {apiKey} as the key for subsequent Analytics requests.
        slots:
          apiKey: query.apiKey
      method: generated
      generated: '2026-09-26'