> ## 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.

# Reading an inventory source: adapter, powering Agent and test runs

> How a seller account reads whether an inventory source is an Apostra-hosted adapter, which Agent powers it, and its latest source tests.

Three facts about an inventory source are readable from V3 without a second tool: whether the source is
Apostra's hosted adapter, which Agent powers it, and how its latest tests went. The first is on every
source. The other two are opt-in, so a `get` that names neither returns exactly what it returned before.

## Is the source an adapter

Every source carries `isAdapterSource`, a boolean. It is on each row of
`search({ "kind": "inventory_source" })` and on the `object` of
`get({ "kind": "inventory_source", "id": "SOURCE_ID" })`.

`isAdapterSource` is `true` when the seller account is routed through an official Apostra-hosted adapter
and this source is that adapter's source. It is `false` for every other source, including an external
sales agent you connected yourself. A caller that wants to tell an Apostra-hosted source from an external
one reads this field instead of working it out from the source's name or endpoint.

Whether Apostra operates a source can also depend on how it executes. A source with
`executionType: "MANAGED_SALES_AGENT"` is operated through an Apostra-managed ad-server connection, and an
adapter source is operated through a hosted adapter, so a caller that means "Apostra runs this source"
treats either as true. `isAdapterSource` answers only the adapter half.

The app names each source by how it executes:

| `executionType` | Shown as |
| - | - |
| `MANAGED_SALES_AGENT`, or any adapter source | Ad-server connection |
| `MODULAR_SOURCE` | Modular source |
| `LINKED_STOREFRONT` | Linked Storefront |
| `AGENT` | Sales agent |
| Any other value | Unrecognized source type |

"Sales agent" does not say who runs the agent: it can be one you run or one a partner runs for you. On a Listing
account that agent is how buyers reach you. On a Storefront account it is one of the sources Apostra's agent sells
from. An `executionType` the app does not know is shown as unrecognized rather than as a sales agent.

The field is `isAdapterSource` and not a single `managed` flag for two reasons. The server already computes
this exact boolean, so the field reports an existing answer rather than a new rule. And `managed` already
means something else on a source: `connection.state: "managed"` says the source is provisioned through its
own flow and has no credentials of yours to enter.

### Listing every source

`search({ "kind": "inventory_source" })` returns up to `limit` sources (at most 200) and, when more match, a
`nextCursor`. Pass it as `cursor` with the same filters to read the next page, and stop when a page comes back
without one. A cursor that is not a whole number is refused with `INVALID_CURSOR`. `total` is the number of
sources that match the filter, so it stays the same on every page. Pages read the list as it stands when each
call is made, so a source added or removed between pages can shift the next page by one.

## Which Agent powers the source

Call `get` with `kind: "inventory_source"`, the source's `id` and `include: ["poweredByAgent"]`. The result
carries `poweredByAgent`, which is one of three things:

```json theme={null}
{ "poweredByAgent": null }
```

```json theme={null}
{
  "poweredByAgent": {
    "state": "ACTIVE",
    "agentId": "AGENT_ID",
    "canOpenAgent": false,
    "agent": {
      "agentId": "AGENT_ID",
      "displayName": "Acme Sales Agent",
      "role": "SALES",
      "operator": { "displayName": "Acme" },
      "authority": "POWERED_BY",
      "liveCertification": { "useCases": [] },
      "implementationHealth": { "status": "HEALTHY" }
    }
  }
}
```

```json theme={null}
{ "poweredByAgent": { "state": "REVOKED" } }
```

| Value | Meaning |
| - | - |
| `null` | No Agent is mapped to this source. An Agent in another organization that has not been authorized for this seller also reads as `null`. |
| `{ "state": "ACTIVE", "agentId", "canOpenAgent", "agent" }` | An Agent powers the source and its mapping is in force. `agentId` is the Agent's id, `canOpenAgent` says whether you can open the Agent's own Page, and `agent` is the limited view of it described below. |
| `{ "state": "REVOKED" }` | An Agent was mapped to the source and no longer is: the mapping or its authorization was revoked, or the Agent was archived. |

There is no other state. "Nothing is mapped" is `null`, not a state of its own.

`canOpenAgent` is `true` only when the Agent lives in a Developer account and you
are Apostra staff or hold a role in that account. Belonging to the same
organization is not enough: a person in a Seller account can have no role in the
organization's Developer account. Show or follow an "Open agent" link only when
`canOpenAgent` is `true`.

## What an active mapping shows about the Agent

`agent` is the limited view a seller gets of an Agent it uses, whether or not it owns the Agent. It is the same
overview the older Powered by read returned, and it is built for a reader who is not the Agent's operator, so it
leaves out what only the operator may know.

| Field | Meaning |
| - | - |
| `agentId`, `displayName`, `role`, `salesMode` | Which Agent it is, what kind it is, and whether it serves wholesale products, composing, or both. A `null` sales mode means it has not been decided. |
| `operator.displayName` | The name of the organization that operates the Agent. It is the only operator fact in the view. |
| `authority` | How you relate to the Agent: `POWERED_BY` when another organization owns it, or `OWNER` when your own account does. It tells you what the Page may offer; it does not grant access. |
| `liveCertification`, `certification` | The Agent's certification. `liveCertification` is current; `certification` is the older seven-requirement summary, kept for existing callers. |
| `implementationHealth` | Whether the Agent's observed implementation matches its deployed one. |
| `validationSkill` | For a Sales Agent, how to run the public validation skill against it. It holds no credentials. |
| `currentSource`, `nextAction`, `links` | Your source this view was opened from, the one next step, and where to open the Agent and the source. |

The view never includes the operator's internal identifier or whether the operator has claimed the Agent, even
for an Agent you own. It carries nothing about the Agent's other customers: no other seller's identity, counts,
traffic, sources or evidence. To read an Agent you own in full, with its diagnostics, call
`get({ "kind": "agent", "id": "AGENT_ID" })`.

## The latest source tests

Call `get` with `kind: "inventory_source"`, the source's `id` and `include: ["testRuns"]`. The result carries
`testRuns`, the five most recent tests recorded for this source, newest first. A source that has never been
tested returns an empty list.

```json theme={null}
{
  "testRuns": [
    {
      "id": "501",
      "toolName": "run_inventory_source_discovery_test",
      "status": "passed",
      "productCount": 12,
      "steps": [
        {
          "key": "get_products-0",
          "label": "Discover products",
          "status": "completed",
          "operation": "get_products",
          "message": null
        }
      ]
    }
  ]
}
```

| Field | Meaning |
| - | - |
| `id` | The run's id. |
| `toolName` | Which test ran: `run_inventory_source_discovery_test` for the read-only product discovery check, or `execute_inventory_source_test_campaign` for the no-spend sandbox campaign test. |
| `status` | `planned`, `partial`, `passed` or `failed`. |
| `productCount` | How many products the test discovered, or `null` when the run did not record a count. |
| `steps` | What the test did, in order. Each step has a `key`, a `label`, a `status` (`completed`, `failed` or `not_checked`), the `operation` it called or `null`, and a `message`, or `null` when the step has nothing to add. |

`get` reads recorded tests. It does not run one, and it does not probe the source. A test belongs to a
source when it was recorded for that source's id or key, so a test recorded without either does not appear.

## Where to ask for them

Both includes belong to `kind: "inventory_source"`. They are refused on any other kind, including
`kind: "seller"`, and a Buyer Account cannot request them.

## When a read fails

There is no "unknown" value. If Apostra cannot work out `poweredByAgent` or `testRuns`, for example because
a lookup timed out, the call fails with `SERVICE_UNAVAILABLE` and returns neither include, so you never act
on a guess. Retry the same call.

## Related

* [Source diagnostics Page](https://docs.apostra.com/v3/seller-source-diagnostics-page.md) opens the diagnostics view for a source.
* [Sellers on the V3 tool surface](https://docs.apostra.com/v3/tool-reference.md) lists every `get` kind and include a seller account reads.


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