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

# List advertiser accounts

> List the sales-agent accounts already linked to an advertiser, with optional filtering by sales agent.



## OpenAPI

````yaml /v2/buyer-api-v2.yaml get /advertisers/{advertiserId}/accounts
openapi: 3.0.0
info:
  title: Scope3 Buyer API
  version: 2.0.0
  description: |-
    REST API for advertisers to manage advertisers, campaigns, and reporting.

    ## Authentication

    All endpoints require a Bearer token in the Authorization header:
    ```
    Authorization: Bearer your-api-key
    ```

    ## Base URL

    `https://api.interchange.io/api/v2/buyer`

    ## For AI Agents

    AI agents can use the MCP endpoint at `/mcp/v2/buyer` with three tools:
    - `initialize`: Start an MCP session
    - `api_call`: Make REST API calls
    - `ask_about_capability`: Learn about API features
servers:
  - url: https://api.interchange.io/api/v2/buyer
    description: Production server
security: []
tags:
  - name: Signup
    description: Request reviewed access to Interchange
  - name: Account
    description: Account management, service tokens, and preferences
  - name: Asks
    description: >-
      What you are waiting on Scope3 for — support, product, and supply asks in
      one list
  - name: Advertisers
    description: Manage advertisers
  - name: Product Discovery
    description: Discover and select products
  - name: Campaigns
    description: Manage advertising campaigns
  - name: Creatives
    description: Build, manage, and sync campaign creatives via AdCP Creative Protocol
  - name: Reporting
    description: Access performance metrics
  - name: Event Sources
    description: >-
      Manage event source configurations and log conversion/marketing events for
      attribution
  - name: Property Lists
    description: Validate property lists against AAO registry
  - name: Sales Agents
    description: View and connect sales agents
  - name: Measurement
    description: Measurement sources, records, context, and freshness
  - name: Syndication
    description: Syndicate resources to ADCP agents
  - name: Tasks
    description: Track async operation status
  - name: Buyer Billing
    description: >-
      Consolidated invoicing for buyers — invoices and pending invoice items
      issued by Scope3 across the buyer customer.
  - name: MCP
    description: Model Context Protocol endpoints for AI agents
paths:
  /advertisers/{advertiserId}/accounts:
    get:
      tags:
        - Advertisers
      summary: List advertiser accounts
      description: >-
        List the sales-agent accounts already linked to an advertiser, with
        optional filtering by sales agent.
      operationId: listAdvertiserAccounts
      parameters:
        - in: query
          name: storefrontId
          schema:
            description: >-
              Filter accounts to those reachable through this storefront. Pair
              with `sourceId`.
            example: 42
            type: integer
            minimum: 0
            exclusiveMinimum: true
            maximum: 9007199254740991
          description: >-
            Filter accounts to those reachable through this storefront. Pair
            with `sourceId`.
        - in: query
          name: sourceId
          schema:
            description: >-
              Filter accounts to those reachable through this inventory source.
              Pair with `storefrontId`.
            example: src_main
            type: string
            minLength: 1
          description: >-
            Filter accounts to those reachable through this inventory source.
            Pair with `storefrontId`.
        - in: query
          name: status
          schema:
            description: Filter by account status
            type: string
            enum:
              - active
              - pending_approval
              - payment_required
              - suspended
              - closed
              - unreachable
          description: Filter by account status
        - in: query
          name: take
          schema:
            default: 50
            description: Number of results to return (max 250)
            example: 50
            type: integer
            minimum: 0
            exclusiveMinimum: true
            maximum: 250
          description: Number of results to return (max 250)
        - in: query
          name: skip
          schema:
            default: 0
            description: Number of results to skip for pagination
            example: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: Number of results to skip for pagination
        - in: path
          name: advertiserId
          schema:
            type: string
            minLength: 1
            description: Unique identifier for the advertiser
            example: '12345'
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: List advertiser accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    AccountListResponse:
      type: object
      properties:
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/AccountSummary'
          description: >-
            Linked accounts projected to the summary shape. Use
            `get_advertiser_account` for the full resource.
        total:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Total count of accounts matching the query
          example: 15
      required:
        - accounts
        - total
      additionalProperties: false
      description: Response containing a paginated list of linked-account summaries
    ErrorResponse:
      type: object
      properties:
        data:
          type: string
          nullable: true
          enum:
            - null
        error:
          $ref: '#/components/schemas/ApiError'
      required:
        - data
        - error
      additionalProperties: false
      description: Standard error response
    AccountSummary:
      type: object
      properties:
        linkId:
          type: string
          description: Unique identifier for the advertiser-account link
          example: '42'
        accountId:
          type: string
          description: Partner account identifier
          example: acc_acme_pinnacle
        name:
          description: Human-readable account name from the partner
          example: Acme c/o Pinnacle
          nullable: true
          type: string
        sources:
          type: array
          items:
            $ref: '#/components/schemas/BuyerCredentialSourceRef'
          description: >-
            Storefront sources that surface this account to the buyer. A single
            linked account may be reachable through multiple sources when the
            underlying agent is shared across storefronts. Empty when the
            underlying agent is no longer linked to any active storefront
            source.
        advertiserId:
          type: string
          description: Advertiser that owns this account link
          example: '12345'
        status:
          type: string
          enum:
            - active
            - pending_approval
            - payment_required
            - suspended
            - closed
            - unreachable
          description: Current account status
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
          description: When the account was created (ISO 8601)
          example: '2025-01-15T10:30:00Z'
        updatedAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
          description: When the account was last updated (ISO 8601)
          example: '2025-01-20T14:45:00Z'
      required:
        - linkId
        - accountId
        - sources
        - advertiserId
        - status
        - createdAt
        - updatedAt
      additionalProperties: false
      description: >-
        Compact linked-account view returned by list endpoints. Use
        `get_advertiser_account` for the full resource.
    ApiError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error message
        field:
          description: Field path associated with the error
          type: string
        details:
          description: Additional error context
          type: object
          additionalProperties: {}
      required:
        - code
        - message
      additionalProperties: false
      description: Structured error object
    BuyerCredentialSourceRef:
      type: object
      properties:
        storefrontId:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Storefront ID this credential covers
        storefrontName:
          type: string
          description: Storefront display name
        sourceId:
          type: string
          description: Inventory source ID within the storefront
        sourceName:
          type: string
          description: Inventory source display name
      required:
        - storefrontId
        - storefrontName
        - sourceId
        - sourceName
      additionalProperties: false
      description: >-
        A storefront/source pair that a single credential row gives the buyer
        access to
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````