EcomScout Audiences API

openapi: 3.2.0
info:
  title: EcomScout Public Audiences API
  version: 0.7.0
  description: Unified ecommerce intelligence API for coding agents, app builders, and VC/PE analysts. Stores, products, apps, analytics, changes, signals, scrapes — one JSON object per resource. Read /v1/llms.txt then /v1/examples before calling data endpoints. Only 2xx responses burn daily quota and plan buckets; 4xx do not. Store contacts (company, emails, phones) on GET /v1/stores/{domain} and GET /v1/stores/{domain}/contacts.
servers:
- url: https://api.ecomscout.com
security:
- apiKey: []
- bearer: []
tags:
- name: Audiences
  description: Segment sizing, compact exports, enrichment, lookalikes, saved audiences. Rows are tiers, not raw metrics; per-store detail stays on /v1/stores/{domain}.
paths:
  /v1/audiences/options:
    get:
      tags:
      - Audiences
      summary: 'Filter vocabulary with store counts: verticals, categories, industries…'
      operationId: audienceOptions
      parameters:
      - name: field
        in: query
        required: true
        schema:
          type: string
          enum:
          - industry
          - vertical
          - category
          - countryCode
          - appSlug
          - mainMarketingChannel
          - sizeTier
          - revenueTier
          - productTier
          - adSpendTier
          - trustpilotTier
      - name: q
        in: query
        schema:
          type: string
        description: Substring filter on the value
      - name: vertical
        in: query
        schema:
          type: string
        description: Scope counts to a vertical
      - name: industry
        in: query
        schema:
          type: string
      - name: countryCode
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          default: 100
          maximum: 500
  /v1/audiences/preview:
    get:
      tags:
      - Audiences
      summary: 'Size a segment: count, withEmail, emailCoveragePct, ceiling, exportable…'
      operationId: audiencePreview
      parameters:
      - name: filters
        in: query
        schema:
          $ref: '#/components/schemas/AudienceDefinition'
        style: form
        explode: true
    post:
      tags:
      - Audiences
      summary: Same as GET with a JSON body (arrays for domains / excludeDomains)
      operationId: audiencePreviewPost
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AudienceDefinition'
  /v1/audiences/export:
    get:
      tags:
      - Audiences
      summary: Export compact rows for a segment.
      operationId: audienceExport
      parameters:
      - name: filters
        in: query
        schema:
          $ref: '#/components/schemas/AudienceDefinition'
        style: form
        explode: true
      - name: include
        in: query
        schema:
          type: string
        description: contacts, channel (comma list)
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - ndjson
          - csv
          default: json
      - name: requireEmail
        in: query
        schema:
          type: boolean
        description: Only rows with a verified email (charges contactReveals)
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - visits
          - revenue
          - domain
          - updated
          default: visits
      - name: limit
        in: query
        schema:
          type: integer
          default: 500
          maximum: 5000
        description: 'Capped by plan: Starter 500, Pro 1000, audiences:bulk 5000'
      - name: cursor
        in: query
        schema:
          type: string
        description: page.nextCursor or x-next-cursor from the previous page. Signed to the filter set and key, 24h
      responses:
        '200':
          description: 'data[] of AudienceRow, page {limit, count, nextCursor, total}, meta {definition, definitionHash, segmentCount, ceiling, limitedBy, charged}. CSV/NDJSON: x-next-cursor, x-total-count, x-page-count headers'
        '422':
          description: 'segment_too_broad: add a narrowing filter or split (details.breakdown)'
        '429':
          description: rate_limited with details.metric = exportRows | contactReveals and resetAt
    post:
      tags:
      - Audiences
      summary: 'Export with a JSON body: filters plus include[], format, requireEmail, sort…'
      operationId: audienceExportPost
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AudienceDefinition'
              - type: object
                properties:
                  include:
                    type: array
                    items:
                      type: string
                      enum:
                      - contacts
                      - channel
                      - matchedApps
                  format:
                    type: string
                    enum:
                    - json
                    - ndjson
                    - csv
                  requireEmail:
                    type: boolean
                  sort:
                    type: string
                  limit:
                    type: integer
                  cursor:
                    type: string
  /v1/audiences/enrich:
    post:
      tags:
      - Audiences
      summary: Compact rows for up to 500 domains you supply; missing[] for unknown domains.
      operationId: audienceEnrich
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domains
              properties:
                domains:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 500
                include:
                  type: array
                  items:
                    type: string
                    enum:
                    - contacts
                    - channel
  /v1/audiences/lookalike:
    post:
      tags:
      - Audiences
      summary: 'Scored lookalikes from 1 to 25 seed domains: learned profile (categories…'
      operationId: audienceLookalike
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - seeds
              properties:
                seeds:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 25
                limit:
                  type: integer
                  default: 25
                  maximum: 100
                excludeSeeds:
                  type: boolean
                  default: true
                include:
                  type: array
                  items:
                    type: string
                filters:
                  $ref: '#/components/schemas/AudienceDefinition'
  /v1/audiences:
    post:
      tags:
      - Audiences
      summary: 'Save an audience: name, description, definition.'
      operationId: createAudience
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - definition
              properties:
                name:
                  type: string
                description:
                  type: string
                definition:
                  $ref: '#/components/schemas/AudienceDefinition'
    get:
      tags:
      - Audiences
      summary: List your saved audiences
      operationId: listAudiences
  /v1/audiences/{id}:
    get:
      tags:
      - Audiences
      summary: One saved audience
      operationId: getAudience
    patch:
      tags:
      - Audiences
      summary: Update name, description and/or definition.
      operationId: updateAudience
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                name:
                  type: string
                  maxLength: 120
                description:
                  type: string
                  maxLength: 600
                definition:
                  $ref: '#/components/schemas/AudienceDefinition'
    delete:
      tags:
      - Audiences
      summary: Delete a saved audience
      operationId: deleteAudience
  /v1/audiences/{id}/changes:
    get:
      tags:
      - Audiences
      summary: Stores that entered (rows) or left (domains) since the snapshot.
      operationId: audienceChanges
      parameters:
      - name: commit
        in: query
        schema:
          type: boolean
          default: false
      - name: include
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          default: 200
          maximum: 500
  /v1/audiences/{id}/export:
    get:
      tags:
      - Audiences
      summary: Export the saved definition (same params and charges as /v1/audiences/export)
      operationId: audienceSavedExport
      parameters:
      - name: include
        in: query
        schema:
          type: string
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - ndjson
          - csv
      - name: requireEmail
        in: query
        schema:
          type: boolean
      - name: sort
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
      - name: cursor
        in: query
        schema:
          type: string
components:
  schemas:
    AudienceDefinition:
      type: object
      description: 'Audience filters. Same keys on GET (comma lists) and POST (arrays). Export requires at least one narrowing key: country, countryCode, vertical, category, industry, appSlug, includeApps, requireApps, includeProducts, mainMarketingChannel, domains or q.'
      properties:
        q:
          type: string
        country:
          type: string
        countryCode:
          type: string
        excludeCountries:
          type: string
        vertical:
          type: string
        excludeVerticals:
          type: string
        category:
          type: string
        industry:
          type: string
        isDropshipper:
          type: boolean
        appSlug:
          type: string
        includeApps:
          type: string
        requireApps:
          type: string
        excludeApps:
          type: string
        appsMatch:
          type: string
          enum:
          - any
          - all
        removedApps:
          type: string
          description: Comma slugs. Stores that uninstalled any of these inside the window (appRemovedSince, default last 30 days). Not excludeApps.
        installedApps:
          type: string
          description: Comma slugs. Stores that newly installed any of these inside the window (appInstalledSince, default last 30 days).
        appRemovedSince:
          type: string
          format: date
        appInstalledSince:
          type: string
          format: date
        newAdsSince:
          type: string
          format: date
        includeProducts:
          type: string
        excludeProducts:
          type: string
        minVisits:
          type: number
        maxVisits:
          type: number
        minRevenue:
          type: number
        maxRevenue:
          type: number
        minRating:
          type: number
        minAdSpend:
          type: number
        maxAdSpend:
          type: number
        minTrustpilotRating:
          type: number
          minimum: 0
          maximum: 5
        minProducts:
          type: integer
        maxProducts:
          type: integer
        sizeTier:
          type: string
          description: Comma list of tier keys
        revenueTier:
          type: string
          description: Comma list of tier keys
        mainMarketingChannel:
          type: string
          description: Organic|Direct|Paid|Social|Referral, comma list
        minVisitsGrowthPct:
          type: number
        growthWindow:
          type: integer
          enum:
          - 1
          - 3
          - 6
        updatedSince:
          type: string
          format: date
        domains:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          description: GET max 200, POST max 500
        excludeDomains:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          description: GET max 200, POST max 5000
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
    bearer:
      type: http
      scheme: bearer