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

# Measures

> Eleven priced paths, one per kind of question. Name the subject, pick the split.

A **measure** is one kind of question: who sells a product and at what price, how prices moved, who holds the shelf, who is talking about it. Each measure is one priced path under `/v1/measures/`, and shares two routing arguments:

* `subject`: what the question is about. Use an appropriate ID from `resolve` (`spt:`, `gpc:`, `brand:`, `retailer:`, `entity:`), or a plain name when the split supports it. Some splits require explicit route parameters instead; omit `subject` in that case. Do not send `subject` and its equivalent route parameter together.
* `by`: how the answer is split. Each measure has a default, so `by` is optional.

```bash theme={null}
curl -i "https://api.syntalic.com/v1/measures/prices?by=distribution&subject=beauty"   # returns 402
```

Each split is answered by one of the existing endpoints, and every other parameter is that endpoint's own (`country`, `retailer`, `window`, ...). The direct routes (such as `/v1/shopper/best-price`) can also be called on their own. Each split still needs the underlying route's required parameters. The answer is that endpoint's answer, unchanged, and the `X-Syntalic-Preset` response header names the endpoint that answered.

## List the measures (free)

```bash theme={null}
curl https://api.syntalic.com/v1/measures
```

Returns each measure with its summary, price, `default_by`, and every `by` split: what it answers, which endpoint answers it, which subject kinds it takes, and an example request. No payment. It always shows which splits are available right now, so check it if a split on this page returns `404`.

## The eleven measures

| Measure | Price | `by` (default first) | Answers |
| - | - | - | - |
| `offers` | \$0.01 | `retailer` | Who sells one product, and at what price, now |
| `prices` | \$0.02 | `summary`, `distribution`, `band`, `brand`, `product`, `retailer` | The price level and spread of a shelf |
| `trend` | \$0.02 | `period`, `drop`, `product` | How prices moved, for a product or a brand (`period`), or the biggest movers on a shelf (`product`) |
| `promotions` | \$0.01 | `brand`, `retailer`, `product` | Who discounts, how often and how deep |
| `assortment` | \$0.02 | `brand`, `concentration`, `category`, `retailer`, `availability` | What is on the shelf, and who holds it |
| `attention` | \$0.03 | `brand`, `product`, `category`, `creator`, `product_type`, `topic`, `momentum`, `emerging`, `week` | Share of social conversation, and how it is moving |
| `signals` | \$0.03 | `brand`, `product_name`, `practice` | What posts say, as labels: launches, reviews, stance, names, practices |
| `scout` | \$0.05 | `gap`, `launch` | Social attention set against the shelf |
| `resolve` | \$0.01 | `name`, `browse_node`, `gpc_browse_nodes`, `gpc_attributes` | A name, phrase or code to ids |
| `neighbors` | \$0.01 | `relations` | What sits next to an id; for a shelf, also the marketing practices and what its posts are (`relations=labels`) |
| `coverage` | \$0.01 | `evidence` | How much evidence stands behind an id |

What each split answers, split by split, is on the [MCP tools](https://syntalic.com/docs/reference/mcp-tools.md#measure-tools) page and in the free listing above. See **Measures** in the API Reference tab for the current parameter schemas.

## Rules

* **One price per measure.** A `/v1/measures/*` path costs the measure's price whichever `by` you pick. Some splits are answered by a cheaper endpoint: `prices` by `brand` is `/v1/marketing/price-positioning` at \$0.01. Call that endpoint directly to pay its own price. The MCP tools do this for you.
* **`trend` by `period`** is a product's price history or a brand's day-by-day tracker. Say which with an `entity:` or `brand:` id, or the matching parameter (`q`, `brand`). A shelf's price movement is `by=product`, the biggest movers.
* **Refused before billing.** Unknown or ambiguous splits and incompatible subjects return `400`; a split that is temporarily unavailable returns `404`. Both are refused before payment. Two splits are currently unavailable: `trend` by `period` for a shelf (price inflation) and `neighbors` by `similar` (similar brands).
* **Use the right scope.** `neighbors` and `coverage` take IDs; `resolve` by `gpc_attributes` or `gpc_browse_nodes` takes a GPC code. For `attention` by `week` use an ID or the route's `subject_kind` and `subject`; for `assortment` by `retailer` use a suitable ID or explicit `brand`/`category`.

## Examples

These are relative GET paths, not shell commands. Prefix each with `https://api.syntalic.com` and use a paid HTTP client.

```text theme={null}
/v1/measures/offers?subject=airpods
/v1/measures/trend?by=drop&subject=airpods
/v1/measures/assortment?by=concentration&subject=electronics
/v1/measures/promotions?by=retailer&subject=grocery
/v1/measures/attention?by=momentum&subject=food-beverages-tobacco&status=new
/v1/measures/scout?subject=food-beverages-tobacco/beverages/soda
/v1/measures/resolve?subject=protein+bars
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.