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

# When Apostra can't read a connection's ad accounts

> After you authorize an ad platform, Apostra reads the ad accounts that sign-in can reach. If that fails, the connection says why and who can fix it.

When you authorize an ad platform such as Meta or TikTok, Apostra reads the ad
accounts that sign-in can reach. Those accounts are what you map your
advertisers to, so a connection is not ready to buy through until the read
works.

If the read fails, the connection shows `error`, and it now also says why and who
can fix it. You or your agent no longer have to guess whether to reconnect.

## Where to read it

Read `accountDiscovery` on a connection with `get` or `search` using
`kind: "connection"` (see the [quickstart](https://docs.apostra.com/v3/quickstart.md) for connecting an agent). A seller read carries the same fact for its connection at
`connectionState.accountDiscovery`. The Connections page uses it to decide
whether to offer Reconnect.

```json theme={null}
{
  "accountDiscovery": {
    "state": "failed",
    "reason": "permission_denied",
    "resolvedBy": "buyer",
    "failedAt": "2026-10-26T10:00:00.000Z"
  }
}
```

`accountDiscovery` describes the connection's latest read of its ad accounts, so
a later successful read replaces an earlier failure. It is `null` until the
first read, and also while the connection's sign-in has expired or been revoked,
because that is the problem to fix first. After a successful read, `state` is `succeeded` and `reason`,
`resolvedBy`, and `failedAt` are `null`.

## Who can fix it

`resolvedBy` names who can fix a failed read. Apostra decides it from the
reason. Show it as it is, and do not work it out again on your side.

| `resolvedBy` | What it means | What to do |
| - | - | - |
| `buyer` | The platform refused the sign-in, or the signed-in user can't see the ad accounts | Connect again, or connect with a user who has access to the ad accounts |
| `apostra` | A setup or internal problem on Apostra's side | Nothing. Apostra is fixing it, and reconnecting won't help |
| `provider` | The platform is rate limiting, unavailable, or returned something Apostra can't use | Try again later. Reconnecting won't help |

## The reasons

| `reason` | `resolvedBy` |
| - | - |
| `authentication_required` | `buyer` |
| `permission_denied` | `buyer` |
| `missing_configuration` | `apostra` |
| `internal_error` | `apostra` |
| `rate_limited` | `provider` |
| `provider_unavailable` | `provider` |
| `provider_rejected` | `provider` |
| `invalid_provider_response` | `provider` |

`failedAt` is when the failed read happened. It is `null` for a failure
recorded before Apostra kept the time.

## Reconnecting

Reconnect only when `resolvedBy` is `buyer`, or when the connection is in
`error` with no failed read. A connection can also be in `error` because its
sign-in expired or was revoked, and connecting again fixes that.

Reconnecting targets the connection you already have. Pass its `connectionId`
to `save_connection` so the new sign-in replaces the broken one instead of
creating a second connection. See [Connecting ad platform
accounts](https://docs.apostra.com/v2/guides/connecting-ad-platforms.md) for how to authorize each
platform.

## When a connection needs a reconnect for new access

A connection can read `connected` and still be missing a permission Apostra asked
for after it was made. Apostra reports this as `credentialAccess` on the same
reads as `accountDiscovery`: on a connection with `get` or `search`, and at
`connectionState.credentialAccess` on a seller read. It is `null` when nothing is
known to be missing.

```json theme={null}
{
  "status": "connected",
  "credentialAccess": {
    "state": "reconnect_required",
    "missingScopes": ["snapchat-profile-api"],
    "affects": "all Snap creatives, because Snap requires a Public Profile on every ad",
    "action": "reconnect",
    "message": "Reconnect needed: this connection was made before Apostra asked for access it needs for all Snap creatives, because Snap requires a Public Profile on every ad. In Snap Business Manager, make sure the connecting user can see the organization's Public Profile, then reconnect it in Apostra."
  }
}
```

This is a note, not a failure. The connection's `status` stays `connected`, and
everything the sign-in already covers keeps working. Only what `affects` names is
refused until you reconnect. The buyer setup read (`get_status` with `include: ["setup"]`) shows the same message as the `reason` of that seller's row, which
stays `ready`, with a reconnect action.

Today this applies to Snap. A Snap connection made before 29 October 2026 lacks
Public Profile access, which every Snap creative needs, because Snap requires a
Public Profile on every ad. To fix it, make sure the Snap user who connects can see the organization's
Public Profile in Snap Business Manager, then reconnect Snap in Apostra, passing
its `connectionId` to `save_connection` as described above. A connection whose
sign-in is a pasted token or API key, or whose scopes were never recorded, is not
flagged.

Without that access no Snap creative can be assigned, so on the `seller` read a
selected Snap partner shows `partnerReadiness` as `needs_you` with the step
`reconnect` until you reconnect (see
[Where a media partner stands](https://docs.apostra.com/v3/media-partner-availability.md#where-a-media-partner-stands-ready-needs-you-or-waiting)).

## Use partner-shared Meta audiences

If a data partner shared a Custom Audience into your Meta ad account, add
Apostra as a partner on that ad account before using the audience in a media
buy. Keep your existing Meta connection: you still connect with your own Meta
login.

A person who can manage partners and assets in the ad account's Meta Business
Portfolio can complete these steps in Meta Business Settings:

1. Open **Users → Partners** and choose **Add → Give a partner access to your assets**.
2. Enter Apostra's Business ID, `1091793362240769`.
3. Select the ad account and grant the campaign management and performance
   reporting access needed for the buy. Add only the Pages, pixels or catalogs
   needed for your campaign. Save the assignment.
4. Tell Apostra which ad account you shared. Apostra must also assign the
   account to its system user before the partner-shared audience can be used.
   Once Apostra confirms the setup, resubmit the buy.

If Meta still refuses the audience, check with Apostra and the data partner that
the audience is shared to the intended ad account. You can instead remove the
audience or choose one created in that account.


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