---
title: "What to do next, ranked, with the evidence"
method: GET
path: "/recommendations"
---

# What to do next, ranked, with the evidence

`GET /recommendations`

## Request

- Base URL: `https://app.aimentiontracker.ai/api/v1`
- URL: `https://app.aimentiontracker.ai/api/v1/recommendations`
- Auth: API key in header `X-API-Key`

CHECK `displayable` BEFORE REPORTING ANYTHING. When it is false the list is empty because the corpus is too thin to rank honestly, NOT because there is nothing to do, and reporting that as a clean bill of health is the worst mistake available on this endpoint. Those two states call for opposite reactions.

Ordered by `tier`, which is an editorial judgement about whose permission the work needs rather than a measurement: your own page outranks a marketplace because nobody has to agree to it. There is deliberately NO blended score. A caller who disagrees with the order can see exactly which judgement to argue with, which is not true of 0.734.

Every row cites the pages behind it. There is no 'write more content' and no 'add schema markup': an item with nothing to point at is filtered out rather than softened into advice.

## Query parameters

- `days` integer
- `limit` integer
- `brand` string

## Response `200`

OK

- object
  - `data` Recommendation[], required
    - `kind` 'own_page' | 'listing' | 'community' | 'marketplace', required: What kind of WORK this is, not what kind of site it is. You submit to a listing, you participate in a community, you rewrite your own page this afternoon.
    - `tier` integer, required: Sort order, and an argument rather than a score: 1 your own page (nobody has to agree), 2 a listing you can submit to this week, 3 a community you must participate in, 4 a marketplace that is usually a procurement decision.
    - `site` string, required: The registrable site. One publisher, one outreach contact.
    - `pages` object[], required: The specific pages, because 'get listed on medium.com' is advice and naming the roundup is a task. Never empty.
      - `url` string, required
      - `title` string, nullable, required
    - `answers` integer, required: Answers in the window that cited this site.
    - `answers_naming_you` integer, required: Of those, how many named you. Zero for every gap, by definition.
    - `competitors_named` integer, required: Distinct tracked competitors named in those answers.
    - `engines` string[], required: Which engines read it. Listed, never pooled into one figure.
    - `share` number, required: Fraction of meta.total_answers this door accounts for. Meaningless without that denominator, which is why it is returned beside it.
  - `meta` object, required
    - `generated_at` string, date-time
    - `brand` BrandRef: Which brand a response describes. Present in meta on every data endpoint.
      - `id` string, required: Pass as ?brand=.
      - `name` string, required: Display name.
    - `note` string
    - `window_days` integer
    - `total_answers` integer: The denominator for every share above.
    - `displayable` boolean: False when the corpus is too thin to rank anything honestly. An empty list with displayable false means NOT YET, never NOTHING TO DO.

## Other responses

- `400`: brand_required, or a cursor that does not belong to this brand.
- `401`: Missing, malformed, revoked or expired key.
- `402`: The organisation has never subscribed, or the plan excludes the API.
- `403`: The key lacks the required scope.
- `404`: No such brand, or the brand has not finished setup.
- `429`: Rate limit exceeded. Carries Retry-After.

---

[API](https://skmtc.dev/aimentiontracker/apis/aimentiontracker-api.md) · [All operations](https://skmtc.dev/aimentiontracker/apis/aimentiontracker-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aimentiontracker/apis/aimentiontracker-api/revisions/c3329178c84c?raw)