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

# Expansion Overview

> Market-level expansion KPIs — per-market stage counts and top cross-border flows. Aggregated, not paginated.



## OpenAPI

````yaml en-openapi POST /expansions/dashboard
openapi: 3.0.0
info:
  description: >-
    The Pubrio API delivers market expansion intelligence — real-time signals
    that flag when a company enters a new market — alongside the company and
    people data beneath them. Search, look up, and enrich accounts and contacts,
    and subscribe to typed, dated movement signals across 200+ markets.
  version: 1.0.0
  title: Pubrio OpenAPI
  termsOfService: https://pubrio.com/en/terms-of-service
  contact:
    email: king.lai@pubrio.com
    name: King Lai
    url: https://pubrio.com/en/get-in-touch
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://api.pubrio.com
security:
  - pubrio_api_key: []
tags:
  - name: Profile
    description: Workspace profile information and usage statistics
  - name: Enrichment
    description: Enrich people and company records with detailed B2B data
  - name: Lookalike
    description: Find companies similar to a given company
  - name: Search
    description: Search for people, companies, jobs, news, and advertisements with filters
  - name: Lookup
    description: >-
      Look up detailed information for specific people, companies, jobs, news,
      advertisements, and technologies
  - name: LinkedIn
    description: Look up people and company data via LinkedIn profile URLs
  - name: Redeem
    description: Redeem credits to unlock people contact details (single and batch)
  - name: Channels
    description: Manage outreach channel templates (create, update, delete, list)
  - name: Monitor
    description: Create and manage data monitors with webhooks, statistics, and processing
  - name: Filters
    description: >-
      Retrieve available filter values for search parameters (technologies,
      locations, verticals, etc.)
  - name: API Keys
    description: List and inspect API request logs and usage analytics for API keys
  - name: Insights
    description: Aggregated signal insights for companies (jobs, news, advertisements).
  - name: Export
    description: Bulk data exports (credit-gated).
  - name: Expansion
    description: >-
      Company market-expansion intelligence: signals, stages, markets, and
      exports.
externalDocs:
  description: >-
    The Pubrio API is used to search, preview and enrich Contacts and Accounts.
    Pubrio database provides extensive B2B contacts and sales intelligence data.
  url: https://docs.pubrio.com
paths:
  /expansions/dashboard:
    post:
      tags:
        - Expansion
      summary: Expansion Overview
      description: >-
        Market-level expansion KPIs — per-market stage counts and top
        cross-border flows. Aggregated, not paginated.
      operationId: expansions_dashboard
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                froms:
                  $ref: '#/components/schemas/expansion_froms'
                tos:
                  $ref: '#/components/schemas/expansion_tos'
                exclude_froms:
                  $ref: '#/components/schemas/expansion_exclude_froms'
                exclude_tos:
                  $ref: '#/components/schemas/expansion_exclude_tos'
                stages:
                  $ref: '#/components/schemas/expansion_stages'
                momentum:
                  $ref: '#/components/schemas/expansion_momentum'
                freshness:
                  $ref: '#/components/schemas/expansion_freshness'
                scopes:
                  $ref: '#/components/schemas/expansion_scopes'
                ahead_of_pace:
                  type: boolean
                  example: false
                  description: >-
                    Limit to company/market pairs moving faster than the typical
                    pace for that market.
                signal_types:
                  $ref: '#/components/schemas/expansion_signal_type_slugs'
                signal_strengths:
                  $ref: '#/components/schemas/signal_strengths'
                min_signal_count:
                  type: integer
                  example: 3
                  description: >-
                    Minimum number of expansion signals a company must have in
                    the window — "very active / heavy footprint".
                only_contraction:
                  $ref: '#/components/schemas/only_contraction'
                verticals:
                  $ref: '#/components/schemas/verticals'
                vertical_categories:
                  $ref: '#/components/schemas/vertical_categories'
                vertical_sub_categories:
                  $ref: '#/components/schemas/vertical_sub_categories'
                technologies:
                  $ref: '#/components/schemas/technologies'
                employees:
                  $ref: '#/components/schemas/employees'
                revenues:
                  $ref: '#/components/schemas/revenues'
                founded_dates:
                  $ref: '#/components/schemas/founded_dates'
                keywords:
                  $ref: '#/components/schemas/keywords'
                companies:
                  $ref: '#/components/schemas/expansion_companies'
                job_locations:
                  $ref: '#/components/schemas/locations'
                job_exclude_locations:
                  $ref: '#/components/schemas/job_exclude_locations'
                job_posted_dates:
                  $ref: '#/components/schemas/posted_dates'
                job_titles:
                  $ref: '#/components/schemas/people_titles'
                advertisement_target_locations:
                  $ref: '#/components/schemas/advertisement_target_locations'
                advertisement_exclude_target_locations:
                  $ref: '#/components/schemas/advertisement_exclude_target_locations'
                advertisement_search_terms:
                  $ref: '#/components/schemas/advertisement_search_terms'
                advertisement_start_dates:
                  $ref: '#/components/schemas/advertisement_start_dates'
                advertisement_end_dates:
                  $ref: '#/components/schemas/advertisement_end_dates'
                news_categories:
                  $ref: '#/components/schemas/news_categories'
                news_published_dates:
                  $ref: '#/components/schemas/published_dates'
                transitioned_dates:
                  type: array
                  items:
                    type: string
                    format: date
                  example:
                    - '2026-06-01'
                    - '2026-06-29'
                  description: >-
                    ISO date range [start, end] for the watchlist timeline.
                    Defaults to the last 30 days.
                window_days:
                  $ref: '#/components/schemas/window_days'
                select_size:
                  type: integer
                  example: 250
                  description: Max markets to return (plan-capped).
                flows_size:
                  type: integer
                  example: 50
                  description: Max cross-border flows to return (plan-capped).
                profile_id:
                  $ref: '#/components/schemas/profile_id'
      responses:
        '200':
          description: Market dashboard aggregates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    type: object
                  data:
                    type: object
                    description: >-
                      Dashboard container: ranked markets plus the top corridor
                      flows.
                    properties:
                      countries:
                        type: array
                        description: Ranked markets with per-market signal counts.
                        items:
                          type: object
                      top_flows:
                        type: array
                        items:
                          type: object
              example:
                metadata:
                  filters:
                    froms:
                      - CN
                    tos:
                      - GB
                  select_size: 250
                  flows_size: 50
                  transitioned_dates:
                    - '2026-06-01'
                    - '2026-06-29'
                data:
                  countries:
                    - country_code: US
                      inbound_count: 18
                      outbound_count: 5
                      total_companies_with_signals: 23
                      exploring_count: 8
                      committing_count: 10
                      expanding_count: 4
                      scaling_count: 1
                      new_transitions_30d: 3
                      freshest_transition_at: '2026-06-27T14:32:10.000Z'
                  top_flows:
                    - home_country_code: SG
                      country_code: US
                      company_count: 5
                      new_transitions_30d: 1
components:
  schemas:
    expansion_froms:
      type: array
      items:
        type: string
      example:
        - US
        - GB
      description: >-
        Origin markets (ISO 3166-1 alpha-2). Where a company is expanding FROM —
        its home / HQ countries. Use alone to find companies growing out of
        these markets; combine with `tos` for a specific from→to corridor.
    expansion_tos:
      type: array
      items:
        type: string
      example:
        - US
        - GB
      description: >-
        Target markets (ISO 3166-1 alpha-2). Where a company is expanding TO.
        Use alone to find every company entering these markets; combine with
        `froms` for a specific from→to corridor.
    expansion_exclude_froms:
      type: array
      items:
        type: string
      example:
        - US
        - GB
      description: Origin markets to exclude (ISO 3166-1 alpha-2).
    expansion_exclude_tos:
      type: array
      items:
        type: string
      example:
        - US
        - GB
      description: Target markets to exclude (ISO 3166-1 alpha-2).
    expansion_stages:
      type: array
      items:
        type: string
        enum:
          - exploring
          - committing
          - expanding
          - scaling
          - established
      example:
        - committing
        - expanding
      description: >-
        Filter to one or more expansion stages. See the Expansion Signals
        knowledge base for stage definitions.
    expansion_momentum:
      type: array
      items:
        type: string
        enum:
          - accelerating
          - advancing
          - steady
          - pulling_back
      example:
        - accelerating
        - advancing
      description: >-
        Filter by expansion momentum (trajectory through the stages):
        `accelerating` (advancing with a mode change), `advancing`, `steady`, or
        `pulling_back` (retreating or contracting).
    expansion_freshness:
      type: array
      items:
        type: string
        enum:
          - fresh
          - cooling
          - stale
          - cold
      example:
        - fresh
        - cooling
      description: >-
        Filter by evidence recency: fresh (~30d), cooling (~30-60d), stale
        (~60-90d), cold (>90d).
    expansion_scopes:
      type: array
      items:
        type: string
        enum:
          - entering_new_market
          - expanding_within_presence
          - established_only
      example:
        - entering_new_market
      description: Filter by market-entry scope.
    expansion_signal_type_slugs:
      type: array
      items:
        type: string
        enum:
          - AD
          - NEWS
          - INFRA
          - PARTNER
          - EVENT_PLUS
          - EXEC
          - OFFICE
          - HIRE
          - SCALE
          - PRODUCT
      example:
        - EXEC
        - HIRE
      description: Filter to specific signal types.
    signal_strengths:
      type: array
      items:
        type: string
        enum:
          - low
          - medium
          - high
          - very_high
      example:
        - high
        - very_high
      description: Filter by signal strength buckets.
    only_contraction:
      type: boolean
      example: false
      description: >-
        When true, return only contraction-flagged expansions (companies scaling
        back).
    verticals:
      type: array
      items:
        type: integer
      description: >-
        A list of `vertical_id` used to search for companies in a specific
        vertical or industry. To find the ID, call the `vertical` endpoint under
        the Filters tab.


        This filter supports `is_enable_similarity_search`, once enabled you can
        enter any free text, e.g. `["AI"]`.
    vertical_categories:
      type: array
      items:
        type: integer
      description: >-
        A list of `vertical_category_id` used to search for companies in a
        specific vertical category. To find the ID, call the `vertical category`
        endpoint under the Filters tab.


        This filter supports `is_enable_similarity_search`, once enabled you can
        enter any free text, e.g. `["Information Technology"]`.
    vertical_sub_categories:
      type: array
      items:
        type: integer
      description: >-
        A list of `vertical_sub_category_id` used to search for companies in a
        specific vertical sub-category. To find the ID, call the `vertical sub
        category` endpoint under the Filters tab.


        This filter supports `is_enable_similarity_search`, once enabled you can
        enter any free text, e.g. `["Software"]`.
    technologies:
      type: array
      items:
        type: integer
      description: >-
        A list of `tag_id` used to search for specific technologies used by
        companies. To find the ID, call the `technology` endpoint under the
        Filters tab.


        This filter supports `is_enable_similarity_search`, once enabled you can
        enter any free text, e.g. `["Shopify"]`.
    employees:
      type: array
      items:
        type: array
        items:
          type: string
      example:
        - - 1
          - 10
        - - 11
          - 20
        - - 10001
      description: >-
        The number range of employees working for the company. This enables you
        to find companies based on headcount. You can add multiple ranges to
        expand your search results. 

         Check out `company size` endpoints under the Filters tab for more information.
    revenues:
      type: array
      items:
        type: integer
      example:
        - 0
        - 100000
      description: Minimum and maximum range of company revenue.
    founded_dates:
      type: array
      items:
        type: integer
      example:
        - 2018
        - 2024
      description: >-
        Years of company founded range. The maximum value founded is the current
        year.
    keywords:
      type: array
      items:
        type: string
      example:
        - ecommerce
        - ai
        - fintech
      description: >-
        A list of keywords to filter companies by relevance, specialties, or
        descriptions.
    expansion_companies:
      type: array
      items:
        type: string
      example:
        - stripe.com
        - https://www.linkedin.com/company/airbnb
        - 550e8400-e29b-41d4-a716-446655440000
      description: >-
        Scope to specific companies by any mix of `domain_search_id`, company
        domain, or a company social media profile URL. Domains and URLs resolve
        to their best-ranked company.
    locations:
      type: array
      items:
        type: string
      example:
        - US
        - SG
        - CN
      description: >-
        ISO 3166-1 alpha-2 (cca2) is used for filtering locations. Check out
        `location` endpoints under the Filters tab for more information.
    job_exclude_locations:
      $ref: '#/components/schemas/exclude_locations'
      description: Geographic locations to exclude from job posting results.
    posted_dates:
      type: array
      items:
        type: string
      example:
        - '2025-01-01'
        - '2025-01-10'
      description: Date range of the posted date. The maximum value is the current day.
    people_titles:
      type: array
      items:
        type: string
      example:
        - sales manager
        - marketing manager
      description: |-
        Job titles associated with the individuals you aim to locate. 

         The results will also encompass job titles that include similar terminology, even if they do not match exactly. For instance, searching for `software engineer` may yield results for individuals with the title `senior software engineer`.
    advertisement_target_locations:
      $ref: '#/components/schemas/target_locations'
      description: Target geographic locations for advertisements.
    advertisement_exclude_target_locations:
      $ref: '#/components/schemas/exclude_target_locations'
      description: Geographic locations to exclude from advertisement targeting.
    advertisement_search_terms:
      type: array
      items:
        type: string
      example:
        - asus
      description: Keywords used to search within advertisement content or titles.
    advertisement_start_dates:
      type: array
      items:
        type: string
        format: date
      example:
        - '2025-12-25'
        - '2025-12-25'
      description: Start date range for advertisement filtering.
    advertisement_end_dates:
      type: array
      items:
        type: string
        format: date
      example:
        - '2025-12-25'
        - '2025-12-25'
      description: End date range for advertisement filtering.
    news_categories:
      type: array
      items:
        type: string
      example:
        - launches
      description: >-
        List of `category slugs` for searching for specific news categories. To
        find a slug, call the `news categories` endpoint under the Filters tab.
    published_dates:
      type: array
      items:
        type: string
      example:
        - '2025-01-01'
        - '2025-01-10'
      description: Date range of the published date. The maximum value is the current day.
    window_days:
      type: integer
      example: 90
      description: >-
        Optional. Size of the rolling window in days. Used when an explicit
        `transitioned_dates` range is not supplied; if both are omitted, a
        default window is used.
    profile_id:
      type: integer
      description: >-
        Optional. An identifier for the user profile (workspace) making the
        request. This is no longer required as the API key already includes your
        workspace information. If provided, it helps in associating the lookup
        with a specific user, allowing for data retrieval and credit tracking. 

         Check out `user details` endpoints under the Profile tab for more information.
    exclude_locations:
      type: array
      items:
        type: string
      example:
        - CN
        - US
        - RU
        - CA
      description: >-
        ISO 3166-1 alpha-2 (cca2) is used to filter out locations that does not
        need to be returned. Check out `location` endpoints under the Filters
        tab for more information.
    target_locations:
      type: array
      items:
        type: string
      example:
        - TW
        - AE
        - 'NO'
      description: >-
        Filter advertisements to include those targeting specific locations by
        country code. Use this to find ads that are being shown in specific
        countries. Combines with `filter_conditions` using OR operator - the
        advertisement must target at least one of the specified locations.
    exclude_target_locations:
      type: array
      items:
        type: string
      example:
        - IS
        - GB
        - FR
        - IE
        - ES
      description: >-
        Filter advertisements to exclude those targeting specific locations by
        country code. Use this to filter out ads that are being shown in
        specific countries. When specified in `filter_conditions` with operator
        'or', the advertisement must not target any of the excluded locations.
  securitySchemes:
    pubrio_api_key:
      type: apiKey
      name: pubrio-api-key
      description: >-
        A unique API token that represents the actions you perform through the
        API and the corresponding permissions and operations. You can create it
        through the [Settings](https://dashboard.pubrio.com/#/settings/)
        section.
      in: header

````