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

# Sessions

> Read your agent's buyer conversations, the recorded commercial context, and the proposal document when one was sent.

## What a Session is

When a buyer asks your storefront for products or a proposal, your storefront
agent answers on your behalf. A **Session** keeps that conversation, including
requests your agent turned down because nothing matched and recorded RFP
exchanges. Open **Sessions** in your seller workspace to see one row per
conversation, newest first.

Open a Session to see buyer and seller turns in their recorded order. Where the
source recorded it, a turn identifies the person or agent who sent it and how it
arrived. A missing detail stays blank rather than being guessed.

For storefront-agent exchanges, the Session shows:

* **What the buyer asked for.** The recorded brief, advertiser or brand,
  channels, countries, flight dates, budget, and creative formats.
* **What your agent answered.** The opening line, products, outcome
  (**Pitched**, **Counter-pitched**, **Passed**, **Asked for more
  information**, or **Forwarded, not checked**), bundles, and lessons that
  shaped the answer. A recorded pass reason is shown when available. When your
  Brief Acceptance check ran, the reason also says what it decided: it allowed
  the brief, could not decide, found a possible conflict with your rules that
  it could not confirm, or found an inventory mismatch while fit declines are
  off. In each of those cases the brief still went on to your agent.
* **The proposal document.** When a proposal was recorded as a document, open
  it from the response to see the immutable proposal the buyer received. It is
  built from the recorded terms, not regenerated later.

A storefront that forwards briefs to its connected sales agent without
composing products, such as a Listing storefront, still gets a Session for each
brief it receives. The Session is marked **Forwarded, not checked**: your sales
agent answered the buyer, and your Brief Acceptance rules were not checked
during product discovery. Only you see these Sessions, never the buyer, and
they are not counted in the daily summary of what your agent answered.

A brief your storefront declined during product discovery also gets a Session,
marked **Passed**, with the decision behind it. When one of your
[Brief Acceptance rules](https://docs.apostra.com/v2/concepts/ai-business-rules.md) turned it away, the
Session quotes that rule. When the brief did not fit your storefront's
inventory, the Session says so and gives the reason. Only you see these
Sessions. The buyer is told only that no products matched, never your rule or
the reason. If you turned on the turn-down alert in
[Session alerts](https://docs.apostra.com/v3/session-alerts.md), you also get one for each declined brief.

Long briefs are shortened to their first 1,200 characters, and each list shows
up to 12 items. The full record remains with the conversation.

## Where Sessions and Training live

**Sessions** appears once in your seller navigation, under **Operate**, beside
Approvals & operations, Media buys and Activity. It is the one record of what
your agent did: buyer exchanges, briefs your rules declined, and the
conversations you had with your assistant. It is not a Storefront agent
destination, so you do not find it there.

The tools you use to teach and test your agent sit in a **Training** section
under **Storefront agent**:

* **Interview** starts a conversation with your assistant, where you teach the
  agent how you sell. Choose **Your interview chats** beneath it to open
  Sessions under **Operate**, filtered to your own conversations with the
  assistant (the **Run by a person** filter).
* **Simulator** opens the [Storefront agent simulator](https://docs.apostra.com/v3/seller-practice-and-simulation.md)
  to test your agent against a buyer brief. The Simulator does not create
  Sessions, so it has no **Your interview chats** link.

Training never lists sessions of its own. Anything the agent did on your behalf
is in Sessions, under **Operate**, once.

## Open the right Sessions

Sign in to the Seller Account that owns the storefront. If you manage more than
one storefront, open **Sessions** from the one you want to review. Your
assistant can tell you which storefront is open and take you to that
storefront's Sessions Page. What you see depends on your current access to that
seller account.

## Why this response

Under an answer, **Why this response** shows the commercial facts recorded with
it. When recorded, this includes the selling approach, offered price against
the target, floor, and ceiling, and the capacity available at the time. It also
shows applied buyer terms, the seller win rate and recommended approach, and
the recorded rule behind a pitch, counter-pitch, or pass. Capacity is **Unknown**
when the source could not resolve it.

This is a record of the facts used for the answer, not the agent's private
reasoning or a new explanation made later. It is visible only to your seller
team.

## Follow one opportunity

When requests carry the same recorded opportunity for the same buyer and seller,
they appear in one Session. This keeps an initial request and later refinements
together without using the buyer's written brief to join them. Requests without
a recorded opportunity remain separate, and the same opportunity from another
buyer or seller is a different Session.

Media buys follow the same rule. A buy placed under a recorded opportunity joins
that opportunity's Session, whether the buyer sent a brief first, sends one
later, or never sends one. Every buy under the same opportunity appears in that
one Session. A buy with no recorded opportunity has a Session of its own. Buys
admitted before this rule started on 2 November 2026 (00:00 UTC) keep the Session they
already had, so their history never moves.

## Follow the buying stage

Each new request and response shows a recorded stage in the Session and in the
Sessions list. **Exploring** means the structured request included no budget,
format, or flight. **Specific request** means it included some of those facts.
**Ready to buy** means it included all three. A refinement request reads
**Refine**, and **Booked** appears after a recorded media-buy forwarding or
delivery report.

The stage comes from structured request fields, refine mode, and recorded
commercial outcomes. It never guesses from the buyer's written brief. Sessions
recorded before stages were added keep their existing history and do not show a
stage.

## Spot a buyer's test

A buyer can test against your storefront with a [sandbox advertiser](https://docs.apostra.com/v3/account-access.md).
Its briefs still get a Session, and your storefront answers them in full, so
the buyer sees the answer a live brief would get. Sandbox Sessions stay in your
Sessions list; nothing is hidden. Sessions recorded before Apostra noted where
a brief came from carry no marker.

The Sessions page shows a **Sandbox** label on each test, in the list and when
you open it. This covers brief responses from a buyer's agent (an RFP in
Proposal Pass) and the briefs your agent composes a response to. Hover the
label for what it means.

When you or your agent read a Session through the API, a test is marked
`sandbox: true` on the Session, in both `get` and `search` with
`kind: "session"`. The page shows the same marker; it decides nothing itself.
It is absent on every other Session, never `false`. It is read-only: you cannot
set it, and you cannot search or filter by it. To find a test, read the marker
on the Sessions you list.

## Who can see what

A Session is your record of your own agent's work. Your team can read it. The
buyer cannot read your side of it.

* Buyers never see your private notes, lessons, commercial facts, or anything
  your storefront exchanged with your inventory sources to fulfil an order.
* Where buyer access to Sessions is switched on, a buyer sees only what passed
  between them and your storefront: their request and your agent's answer.
  Where it is not, a buyer account that asks for Sessions is refused with
  `ACCESS_DENIED`: buyer Session reads are not enabled for that account.
* Another seller can never see your Sessions.

## Read Sessions from your own agent

Your agent, or any assistant signed in as you, can do what the Sessions page
does. It lists your Sessions with `search` and reads one with `get`, both with
`kind: "session"`, and it leaves a private note with `save_session`. These are
the same calls the page makes, with the same rules: your seller account needs a
current storefront, and a note needs write access. See the
[tool reference](https://docs.apostra.com/v3/tool-reference.md#sessions).

## Leave a private note

Under any event in a Session, you can write a **private note**: what you
liked, what you would have done differently, or what the agent should know next
time. For example: "For stationery brands, lead with the lifestyle video
package." This includes a media-buy Session, where the events are the buyer's
orders and your agent gives no answer.

A note is only for you and your team. It is never sent to the buyer and it does
not change what your agent does on its own. Turn it into a lesson if you want
the agent to act on it next time.

## Teach your agent from a note

Every seller storefront can use **Teach this** on a note saved under an answer
your agent gave. Notes on other events, such as a buyer's order, are for your
team and do not offer it. **Teach this** turns your note into a proposed [lesson](https://docs.apostra.com/v3/lessons.md): short guidance, in
your own words, that your agent follows on future matching briefs after an
administrator approves it.

## If an answer was wrong

An answer from your agent is a proposal, not a booking. Media buys wait for
your approval unless you chose automatic approval; manual approval is the
default.

* **Correct it for next time.** Leave a note and teach a lesson from it.
* **Stop new business while you sort it out.** Pause your storefront. Buyers
  stop seeing your products and cannot place new buys, while campaigns already
  running keep delivering. Unpause when you are ready.
* **Choose alerts if you want them.** [Session alerts](https://docs.apostra.com/v3/session-alerts.md) are
  optional. You can opt in to an alert when your agent turns down a buyer
  request, a daily summary, or both.

## Availability

Every seller can use Sessions and Lessons for the storefront they own. The Page
shows the sources available to your storefront.

## Related

> [card] [Lessons](https://docs.apostra.com/v3/lessons.md)
>
> Turn your notes into guidance your agent follows

> [card] [Session timeline (API)](https://docs.apostra.com/v3/session-timeline.md)
>
> Read Sessions and save notes from your own tools


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