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

# Concepts and entity model

> Every word Attensira uses, what it means, and the wire field an MCP user actually sees.

Attensira uses a small vocabulary, and each word means exactly one thing. This page defines every term, then maps the customer-facing words onto the field names you will meet in the API and through MCP.

## The tracked objects

**Prompt** — one question, phrased the way a buyer would phrase it. Prompts are the unit you pay for: your plan grants 50, 150, or 350 slots.

**Topic** — a named group of related prompts, so you can read a whole buying question as one line instead of twenty.

**Model** — a model surface Attensira asks, identified by a stable channel id: `chatgpt`, `perplexity`, `google_ai`, `claude`, `gemini`. The channel is deliberately stable, so when the vendor swaps the underlying model behind that surface, your history stays continuous.

**Workspace** — the container for prompts, competitors, models, automations, and data. An API key names exactly one workspace, which is why no MCP tool takes a workspace id.

**Answer** — one stored response from one Model to one Prompt on one day. Answers are the raw material every metric is folded from.

## What we read out of an answer

**Mention** — the answer named your brand in its text, with no link attached.

**Citation** — the model attached one URL, and that URL points at your own domain.

**Source** — a domain bucket across citations. Sources cover every domain the models cite for your prompts, not only yours, so you can see which sites the answers lean on.

Mentions and citations are counted independently. An answer can do either, both, or neither.

## The metrics

<Note>
  Every rate is `{value, n}`. `n` is the number of **successful** runs behind it; failed runs are stored but excluded. `value: null` means not measured. `value: 0` with `n > 0` is a real, measured zero.
</Note>

**Mention rate** — successful runs naming your brand, over all successful runs.

**Citation rate** — successful runs citing your own domain, over all successful runs.

**Competitor rates** — the same calculation for a competitor, over the same denominator. They do not sum to 1, and they were never meant to.

**Source share** — citations to a given domain over all citations in the window.

**Average position** — the mean index of a URL inside the model's citation list, calculated **per source domain**. It describes where a domain tends to sit in a citation list. It is not a rank of your brand against competitors.

Deltas are `{value, real}` and pass a two-proportion z-test at 95%. Below the noise floor you get `{real: false, value: null}`: no change we can prove, which is not the same as no change.

Per-model figures carry `tracked` and `readable`. `tracked: false` means the model is not configured for this workspace and was never asked — reporting it as 0% invents a failure. `readable: false` means no reader exists for that surface.

<Warning>
  There is no visibility metric, no sentiment score, no brand rank, and no share-of-voice that sums to 1. "Visibility" is a label in the interface, not a number. If you see a field named `ShareOfVoice`, it is the brand's own mention rate under an older name.
</Warning>

## The working layer

**Credit** — the unit spent by work that costs money to run. Adding prompts, running an automation, and asking the agent all spend credits. Reading numbers you already have does not.

**Automation** — a saved piece of recurring work the agent performs on its own.

**Chat** — a conversation with the agent about your workspace.

**Agent model** — the LLM your chat runs on, listed at `GET /v2/models`. This is a different thing from a **Model**: an agent model answers you, a Model is a surface Attensira measures.

<Warning>
  Credits and the response budget are currently inconsistent in the product. Treat credit arithmetic as approximate until that is fixed, and check your account before planning around a specific balance.
</Warning>

## Words to wire fields

The wire format kept its original names, and this is deliberate: renaming fields would break every existing integration, so the product vocabulary changed and the contract did not. When the docs and the JSON disagree on a name, both are correct.

| Customer word | Wire field   | Appears in                                           |
| ------------- | ------------ | ---------------------------------------------------- |
| Prompt        | `keyword_id` | `get_prompt`, analytics rows, automation payloads    |
| Topic         | `group_id`   | analytics rows, `get_analytics` with `area: "group"` |
| Model         | `channel`    | analytics rows, per-model breakdowns                 |
| Workspace     | `project_id` | internal identifiers; never a tool argument          |

The same holds for enum values. The `get_analytics` `area` enum accepts `visibility`, `prompt`, `page`, `source`, `competitor`, `group`, `engine`, and `bot` — `group` means Topic and `engine` means Model. Those strings are the contract; pass them exactly as written.

## Crawlers are not models

An AI crawler fetches your pages. A model answers prompts. Attensira reports both, and they never mix: a crawler visit is not a reading, and a mention is not a pageview. See [AI traffic](/traffic/ai-traffic) for what the crawler side does and does not tell you.