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

# List ad accounts

> The Meta ad accounts this workspace has connected, so Pilot Status can resolve the ad, ad set and campaign **names** of your Click-to-WhatsApp traffic, plus the accounts you can still connect.

There is no Meta login step: the advertiser adds the Pilot Status business portfolio (`partnerBusinessId`) as a **partner** of the ad account in Meta Business Manager, and Pilot Status reads with its own system user.

**Account-wide credential only** (a number-scoped key is refused with `403 NUMBER_SCOPE_NOT_ALLOWED`): an ad account belongs to the workspace, not to a number. OAuth/MCP tokens need `integrations:manage` (workspace ADMIN or OWNER) on every verb, reads included.

`linked` are the active links; `sharingActive` is `true` while the partner grant is still in place, `false` when the advertiser revoked it, and `null` when Meta could not be asked right now (never read `null` as revoked). `candidates` are accounts shared with Pilot Status that provably belong to this workspace — an ad from them already reached one of your numbers — and are not linked yet; a new workspace starts with an empty list. `sharingLookup` is `ok`, `unavailable` (Meta could not be reached; `linked` still comes back) or `not_configured`.



## OpenAPI

````yaml openapi.json GET /v1/ads/accounts
openapi: 3.1.0
info:
  title: Pilot Status API
  version: 1.0.0
  license:
    name: Pilot Status Terms of Service
    url: https://pilotstatus.com.br/terms
  description: >-
    Public REST API for Pilot Status. Authenticate with the `x-api-key: ps_...`
    header (or `x-api-key-id`). Base URL: https://pilotstatus.com.br
servers:
  - url: https://pilotstatus.com.br
security:
  - apiKey: []
  - apiKeyId: []
paths:
  /v1/ads/accounts:
    get:
      tags:
        - Ads
      summary: List ad accounts
      description: >-
        The Meta ad accounts this workspace has connected, so Pilot Status can
        resolve the ad, ad set and campaign **names** of your Click-to-WhatsApp
        traffic, plus the accounts you can still connect.


        There is no Meta login step: the advertiser adds the Pilot Status
        business portfolio (`partnerBusinessId`) as a **partner** of the ad
        account in Meta Business Manager, and Pilot Status reads with its own
        system user.


        **Account-wide credential only** (a number-scoped key is refused with
        `403 NUMBER_SCOPE_NOT_ALLOWED`): an ad account belongs to the workspace,
        not to a number. OAuth/MCP tokens need `integrations:manage` (workspace
        ADMIN or OWNER) on every verb, reads included.


        `linked` are the active links; `sharingActive` is `true` while the
        partner grant is still in place, `false` when the advertiser revoked it,
        and `null` when Meta could not be asked right now (never read `null` as
        revoked). `candidates` are accounts shared with Pilot Status that
        provably belong to this workspace — an ad from them already reached one
        of your numbers — and are not linked yet; a new workspace starts with an
        empty list. `sharingLookup` is `ok`, `unavailable` (Meta could not be
        reached; `linked` still comes back) or `not_configured`.
      operationId: get_ads-accounts
      responses:
        '200':
          description: Linked and linkable ad accounts
          content:
            application/json:
              example:
                linked:
                  - adAccountId: act_1234567890
                    adAccountName: MM Design
                    linkedAt: '2026-10-05T14:02:11.000Z'
                    sharingActive: true
                candidates:
                  - adAccountId: act_9876543210
                    adAccountName: MM Design — Black Friday
                    accountStatus: 1
                partnerBusinessId: '123456789012345'
                sharingLookup: ok
        '401':
          description: Missing or invalid `x-api-key` / `x-api-key-id` header
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: Unauthorized
        '403':
          description: >-
            Number-scoped key (this endpoint needs an account-wide credential),
            or an OAuth token whose workspace role lacks `integrations:manage`
            (`PERMISSION_DENIED`)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: This endpoint requires a tenant-scoped API key
                code: NUMBER_SCOPE_NOT_ALLOWED
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: Internal server error | Erro interno do servidor
                code: INTERNAL_ERROR
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your ps_ API key
    apiKeyId:
      type: apiKey
      in: header
      name: x-api-key-id
      description: API key id (alternative to x-api-key)

````

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