> ## Documentation Index
> Fetch the complete documentation index at: https://architect-d889a35e-dependabot-github-actions-actions-checko-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get audience

> Get an audience.



## OpenAPI

````yaml /services/external-actor-gateway-service/openapi.yaml get /v0/pages/{page_id}/audiences/{audience_id}
openapi: 3.1.0
info:
  contact:
    email: api-support@tryarchitect.com
    name: Architect
    url: https://tryarchitect.com
  description: >-
    The Customer API lets you manage pages, audiences, persons, accounts,
    topics, page links, analytics, and webhook subscriptions.


    ## Authentication

    Send your API key in the `x-api-key` header on every request.


    ## Terminology

    - **Page**: a top-level customer experience container.

    - **Audience**: a targeted experience that belongs to a Page.

    - **Version**: a generated or editable Audience state, including drafts and
    published versions.

    - **Person**: an individual contact record.


    ## Pagination

    Collection endpoints use `limit` and `cursor`. When another page is
    available, pass the returned `nextCursor` value back as `cursor`. When there
    are no more results, `nextCursor` is `null`.


    ## Webhooks

    Create subscriptions with `POST /v0/webhook_subscriptions`. The
    `signingSecret` is returned only once, when the subscription is created, so
    store it securely.


    Webhook deliveries are sent as `POST` requests with these headers:

    - `X-Webhook-Signature-256`: HMAC-SHA256 of the raw request body, prefixed
    with `sha256=`

    - `X-Webhook-Timestamp`: Unix timestamp in milliseconds used when the
    signature was generated


    Webhook deliveries are at-least-once. Use `eventId` for idempotency and
    return a `2xx` response quickly after persisting work.


    Example delivery body:

    ```json

    {
      "timestamp": "2024-01-15T10:30:00.000Z",
      "eventId": "event_01j5k9m7n8p9q2r3s4t5v6w7x8",
      "payload": {
        "type": "page.version.created",
        "pageId": "page_01j5k9m7n8p9q2r3s4t5v6w7x8",
        "versionId": "<audience_version_id>",
        "createdAt": "2024-01-15T10:30:00.000Z"
      }
    }

    ```


    Version webhook event names currently use the internal `page.version.*`
    namespace. In Customer API terms, these correspond to Audience version
    lifecycle events.
  title: Architect - Customer API
  version: 0.0.1
servers:
  - description: Production environment
    url: https://api.tryarchitect.com
  - description: Beta environment
    url: https://api.beta.tryarchitect.com
  - description: Local environment
    url: http://localhost:25001
security:
  - apiKey: []
tags:
  - name: Pages
    description: Page management operations
  - name: Analytics
    description: Analytics and session read operations
  - name: Audiences
    description: Audience management operations
  - name: Audience Versions
    description: Audience version management operations
  - name: Audience Messages
    description: Audience message editing operations
  - name: Page Link Blocks
    description: Shared footer and navigation link block management operations
  - name: Page Links
    description: Page link management operations
  - name: Tenant Domains
    description: Tenant domain discovery operations
  - name: Assets
    description: Asset management operations
  - name: Persons
    description: Person management operations
  - name: Person Logs
    description: Person log ingestion operations
  - name: Accounts
    description: Account management operations
  - name: Account Activity
    description: Merged account and linked person activity operations
  - name: Account Logs
    description: Account log ingestion operations
  - name: Topics
    description: Knowledge topic management operations
  - name: Topic Entries
    description: Knowledge topic entry management operations
  - name: Webhook Subscriptions
    description: Webhook subscription management operations
paths:
  /v0/pages/{page_id}/audiences/{audience_id}:
    get:
      tags:
        - Audiences
      summary: Get audience
      description: Get an audience.
      operationId: getAudience
      parameters:
        - $ref: '#/components/parameters/PageIdPath'
        - $ref: '#/components/parameters/AudienceIdPath'
      responses:
        '200':
          $ref: '#/components/responses/PostAudienceResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
components:
  parameters:
    PageIdPath:
      in: path
      name: page_id
      description: page_id parameter
      required: true
      schema:
        type: string
    AudienceIdPath:
      in: path
      name: audience_id
      description: audience_id parameter
      required: true
      schema:
        type: string
  responses:
    PostAudienceResponse:
      description: Audience created successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PostAudience'
    ValidationError:
      content:
        application/json:
          examples:
            default:
              value:
                code: VALIDATION_ERROR
                detail: 'body - name: Name is required; email: Invalid email address'
                details:
                  - field: body
                    issues:
                      - code: validation_failed
                        message: 'name: Name is required'
                        path:
                          - name
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 400
                title: Bad Request
                type: https://api.tryarchitect.com/errors/validation_error
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The request could not be processed because the path, query string, or
        JSON body was invalid.
    UnauthorizedError:
      content:
        application/json:
          examples:
            default:
              value:
                code: UNAUTHORIZED
                detail: Authentication is required
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 401
                title: Unauthorized
                type: https://api.tryarchitect.com/errors/unauthorized
          schema:
            $ref: '#/components/schemas/Error'
      description: The request did not include valid authentication credentials.
    ForbiddenError:
      content:
        application/json:
          examples:
            default:
              value:
                code: FORBIDDEN
                detail: Multi-tenant API keys are not supported
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 403
                title: Forbidden
                type: https://api.tryarchitect.com/errors/forbidden
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The caller is authenticated but does not have access to the requested
        tenant or operation.
    NotFoundError:
      content:
        application/json:
          examples:
            default:
              value:
                code: NOT_FOUND
                detail: Audience not found
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 404
                title: Not Found
                type: https://api.tryarchitect.com/errors/not_found
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The referenced resource does not exist, is not owned by the requested
        parent, or is not visible to the authenticated tenant.
    RateLimitError:
      content:
        application/json:
          examples:
            default:
              value:
                code: RATE_LIMITED
                detail: Rate limit exceeded
                details:
                  limit: 100
                  remaining: 0
                  resetTime: 1713225600000
                  retryAfter: 60
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 429
                title: Too Many Requests
                type: https://api.tryarchitect.com/errors/rate_limited
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The authenticated caller has exceeded the current request rate limit
        window.
    InternalServerError:
      content:
        application/json:
          examples:
            default:
              value:
                code: INTERNAL
                detail: An unexpected error occurred
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 500
                title: Internal Server Error
                type: https://api.tryarchitect.com/errors/internal
          schema:
            $ref: '#/components/schemas/Error'
      description: The server encountered an unexpected error while processing the request.
    ServiceUnavailableError:
      content:
        application/json:
          examples:
            default:
              value:
                code: SERVICE_UNAVAILABLE
                detail: The service is temporarily unavailable
                requestId: req_01j5k9m7n8p9q2r3s4t5v6w7x8
                status: 503
                title: Service Unavailable
                type: https://api.tryarchitect.com/errors/service_unavailable
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The service is temporarily unavailable. Retry the request after a short
        delay.
  schemas:
    PostAudience:
      type: object
      properties:
        actionFormIdOverride:
          anyOf:
            - type: string
            - type: 'null'
        actionFormInstructionsOverride:
          anyOf:
            - type: string
            - type: 'null'
        actionUrlOverride:
          anyOf:
            - type: string
            - type: 'null'
        archivedAt:
          anyOf:
            - $ref: '#/components/schemas/UnnamedSchema'
            - type: 'null'
        audienceId:
          type: string
        computedName:
          type: string
        createdAt:
          $ref: '#/components/schemas/UnnamedSchema'
        customName:
          anyOf:
            - type: string
            - type: 'null'
        effectiveMetadata:
          $ref: '#/components/schemas/Metadata'
        effectiveName:
          type: string
        flags:
          type: array
          items:
            type: string
            enum:
              - home_page
        isNewPageAgent:
          type: boolean
        latestVersion:
          anyOf:
            - $ref: '#/components/schemas/PostVersion'
            - type: 'null'
        metadataOverride:
          $ref: '#/components/schemas/Metadata'
        pageId:
          type: string
        personId:
          anyOf:
            - type: string
            - type: 'null'
        personRouteKey:
          anyOf:
            - type: string
            - type: 'null'
        publishedVersion:
          anyOf:
            - $ref: '#/components/schemas/PostVersion'
            - type: 'null'
        status:
          type: string
          enum:
            - archived
            - cancelled
            - draft
            - pending
            - processing
            - published
            - queued
        supplementaryContext:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - actionFormIdOverride
        - actionFormInstructionsOverride
        - actionUrlOverride
        - archivedAt
        - audienceId
        - computedName
        - createdAt
        - customName
        - effectiveName
        - flags
        - isNewPageAgent
        - latestVersion
        - pageId
        - personId
        - personRouteKey
        - publishedVersion
        - status
        - supplementaryContext
      additionalProperties: false
    Error:
      properties:
        code:
          enum:
            - UNAUTHORIZED
            - FORBIDDEN
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - RATE_LIMITED
            - INTERNAL
            - SERVICE_UNAVAILABLE
          examples:
            - VALIDATION_ERROR
            - UNAUTHORIZED
            - NOT_FOUND
          type: string
        detail:
          examples:
            - Authentication is required
            - Audience not found
            - Default topic titles cannot be updated
          type: string
        details:
          description: >-
            Optional structured details about the error, such as validation
            issues or rate-limit metadata.
          examples:
            - - field: body
                issues:
                  - code: validation_failed
                    message: 'name: Name is required'
                    path:
                      - name
            - limit: 100
              remaining: 0
              resetTime: 1713225600000
              retryAfter: 60
          oneOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - additionalProperties: true
              type: object
        requestId:
          examples:
            - req_01j5k9m7n8p9q2r3s4t5v6w7x8
          type: string
        status:
          example: 400
          type: number
        title:
          examples:
            - Bad Request
            - Unauthorized
            - Not Found
          type: string
        type:
          examples:
            - https://api.tryarchitect.com/errors/validation_error
            - https://api.tryarchitect.com/errors/not_found
          type: string
      required:
        - code
        - detail
        - requestId
        - status
        - title
        - type
      type: object
    UnnamedSchema:
      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))$
    Metadata:
      type: object
      properties:
        title:
          anyOf:
            - type: string
            - type: 'null'
        description:
          anyOf:
            - type: string
            - type: 'null'
        keywords:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
        author:
          anyOf:
            - type: string
            - type: 'null'
        robots:
          anyOf:
            - type: array
              items:
                type: string
                enum:
                  - index
                  - noindex
                  - follow
                  - nofollow
                  - noarchive
                  - nosnippet
                  - noimageindex
                  - none
            - type: 'null'
        canonicalUrl:
          anyOf:
            - type: string
            - type: 'null'
        ogTitle:
          anyOf:
            - type: string
            - type: 'null'
        ogDescription:
          anyOf:
            - type: string
            - type: 'null'
        ogType:
          anyOf:
            - type: string
              enum:
                - website
                - article
                - product
                - profile
            - type: 'null'
        ogImageUrl:
          anyOf:
            - type: string
            - type: 'null'
        ogImageFileId:
          anyOf:
            - type: string
            - type: 'null'
        ogImageAlt:
          anyOf:
            - type: string
            - type: 'null'
        ogSiteName:
          anyOf:
            - type: string
            - type: 'null'
        ogUrl:
          anyOf:
            - type: string
            - type: 'null'
        twitterCard:
          anyOf:
            - type: string
              enum:
                - summary
                - summary_large_image
                - app
                - player
            - type: 'null'
        twitterTitle:
          anyOf:
            - type: string
            - type: 'null'
        twitterDescription:
          anyOf:
            - type: string
            - type: 'null'
        twitterImageUrl:
          anyOf:
            - type: string
            - type: 'null'
        twitterImageFileId:
          anyOf:
            - type: string
            - type: 'null'
        twitterImageAlt:
          anyOf:
            - type: string
            - type: 'null'
        twitterSite:
          anyOf:
            - type: string
            - type: 'null'
        twitterCreator:
          anyOf:
            - type: string
            - type: 'null'
        themeColor:
          anyOf:
            - type: string
            - type: 'null'
      additionalProperties: false
    PostVersion:
      type: object
      properties:
        archivedAt:
          anyOf:
            - $ref: '#/components/schemas/UnnamedSchema'
            - type: 'null'
        audienceId:
          type: string
        becameDraftAt:
          anyOf:
            - $ref: '#/components/schemas/UnnamedSchema'
            - type: 'null'
        cancelledAt:
          anyOf:
            - $ref: '#/components/schemas/UnnamedSchema'
            - type: 'null'
        createdAt:
          $ref: '#/components/schemas/UnnamedSchema'
        isNewPageAgent:
          type: boolean
        obsoleteAt:
          anyOf:
            - $ref: '#/components/schemas/UnnamedSchema'
            - type: 'null'
        publishedAt:
          anyOf:
            - $ref: '#/components/schemas/UnnamedSchema'
            - type: 'null'
        queueDurationMs:
          anyOf:
            - type: number
            - type: 'null'
        queuedAt:
          anyOf:
            - $ref: '#/components/schemas/UnnamedSchema'
            - type: 'null'
        status:
          type: string
          enum:
            - archived
            - cancelled
            - draft
            - pending
            - processing
            - published
            - queued
        supplementaryContext:
          anyOf:
            - type: string
            - type: 'null'
        versionId:
          type: string
        versionNumber:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
      required:
        - archivedAt
        - audienceId
        - becameDraftAt
        - cancelledAt
        - createdAt
        - isNewPageAgent
        - obsoleteAt
        - publishedAt
        - queueDurationMs
        - queuedAt
        - status
        - supplementaryContext
        - versionId
        - versionNumber
      additionalProperties: false
  securitySchemes:
    apiKey:
      description: API key authentication for the External Actor Gateway
      in: header
      name: x-api-key
      type: apiKey

````