{"uid":"cap_EPTNHGBVuFYRwQbz7eEX3","slug":"agents-pubrio-com-expansion-rankings-bad0ca91","name":"Expansion Rankings","description":"Lightweight ranked list of company/market pairs by expansion score — suited to map or heatmap rendering.","url":"https://agents.pubrio.com/expansions/companies/rankings?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"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."},"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."},"stages":{"type":"array","allOf":[{"type":"array","items":{"enum":["exploring","committing","expanding","scaling"],"type":"string"},"example":["committing","expanding"],"description":"Filter to one or more expansion stages. See the Expansion Signals knowledge base for stage definitions."}],"items":{"type":"string","description":"Allowed values: exploring, committing, expanding, scaling."},"example":["committing","expanding"],"description":"Values are case-sensitive and are **not validated**. An unrecognised value is silently discarded rather than rejected: on `stages`, `freshness`, `scopes` and `momentum` the whole filter is dropped and you get *unfiltered* results, while on `signal_types` and `signal_strengths` the filter is applied and matches *nothing*. Either way the response looks normal. Resolve valid slugs from [Expansion Reference](/en/api-reference/endpoint/expansions/types) and compare `data.pagination.total_entries` against an unfiltered call if a result set looks wrong."},"filters":{"type":"object"},"keywords":{"type":"array","items":{"type":"string"},"example":["ecommerce","ai","fintech"],"description":"A list of keywords to filter companies by relevance, specialties, or descriptions."},"revenues":{"type":"array","items":{"type":"integer"},"example":[0,100000],"description":"Minimum and maximum range of company revenue."},"companies":{"type":"array","items":{"type":"string"},"example":["stripe.com","https://www.linkedin.com/company/airbnb","b7d92a56-31f8-4c0b-ae43-19c8e5f24b70"],"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."},"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. \n\n Check out `company size` endpoints under the Filters tab for more information."},"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.\n\nThis filter supports `is_enable_similarity_search`, once enabled you can enter any free text, e.g. `[\"AI\"]`."},"job_titles":{"type":"array","items":{"type":"string"},"example":["sales manager","marketing manager"],"description":"Job titles associated with the individuals you aim to locate. \n\n 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`."},"exclude_tos":{"type":"array","items":{"type":"string"},"example":["US","GB"],"description":"Target markets to exclude (ISO 3166-1 alpha-2)."},"select_size":{"type":"integer","example":50,"description":"Maximum number of records to return. Capped by your plan."},"signal_types":{"type":"array","allOf":[{"type":"array","items":{"enum":["AD","AUDIENCE","DNS","ENTITY","EVENT","EVENT_PLUS","EXEC","HIRE","INFRA","IP","NEWS","OFFICE","PARTNER","PRODUCT","REG","SCALE","TECH"],"type":"string"},"example":["EXEC","HIRE"],"description":"Filter to specific signal types. See the Signal Types catalog in the knowledge base for definitions and tiers (`DNS` and `INFRA` are Premier-tier signals)."}],"items":{"type":"string","description":"Allowed values: AD, AUDIENCE, DNS, ENTITY, EVENT, EVENT_PLUS, EXEC, HIRE, INFRA, IP, NEWS, OFFICE, PARTNER, PRODUCT, REG, SCALE, TECH."},"example":["EXEC","HIRE"],"description":"Values are case-sensitive and are **not validated**. An unrecognised value is silently discarded rather than rejected: on `stages`, `freshness`, `scopes` and `momentum` the whole filter is dropped and you get *unfiltered* results, while on `signal_types` and `signal_strengths` the filter is applied and matches *nothing*. Either way the response looks normal. Resolve valid slugs from [Expansion Reference](/en/api-reference/endpoint/expansions/types) and compare `data.pagination.total_entries` against an unfiltered call if a result set looks wrong."},"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.\n\nThis filter supports `is_enable_similarity_search`, once enabled you can enter any free text, e.g. `[\"Shopify\"]`.\n\nA product name the technology list knows matches that product and its own products (`\"Salesforce\"` also matches Salesforce Desk and Salesforce Service Cloud), never look-alikes; other text matches by similarity."},"exclude_froms":{"type":"array","items":{"type":"string"},"example":["US","GB"],"description":"Origin markets to exclude (ISO 3166-1 alpha-2)."},"founded_dates":{"type":"array","items":{"type":"integer"},"example":[2018,2024],"description":"Years of company founded range. The maximum value founded is the current year."},"job_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."},"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."},"job_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. Day boundaries follow your workspace timezone."},"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":{"type":"boolean","example":false,"description":"When true, return only contraction-flagged expansions (companies scaling back)."},"signal_strengths":{"type":"array","allOf":[{"type":"array","items":{"enum":["low","medium","high","very_high"],"type":"string"},"example":["high"],"description":"Filter by evidence-confidence bucket: `low`, `medium`, or `high`. Note this is distinct from the per-signal `signal_strength_slug` returned on signal records (which ranges `low` to `very_high`); any other value here matches nothing."}],"items":{"type":"string","description":"Allowed values: low, medium, high, very_high."},"example":["high"],"description":"Values are case-sensitive and are **not validated**. An unrecognised value is silently discarded rather than rejected: on `stages`, `freshness`, `scopes` and `momentum` the whole filter is dropped and you get *unfiltered* results, while on `signal_types` and `signal_strengths` the filter is applied and matches *nothing*. Either way the response looks normal. Resolve valid slugs from [Expansion Reference](/en/api-reference/endpoint/expansions/types) and compare `data.pagination.total_entries` against an unfiltered call if a result set looks wrong."},"domain_search_ids":{"type":"array","allOf":[{"type":"array","items":{"type":"string"},"example":["8f3c1b04-2e7a-4d19-9c55-6ab21f0e7d3c"],"description":"Company identifiers (domain_search_id UUIDs) to include."}],"items":{"type":"string"},"example":["8f3c1b04-2e7a-4d19-9c55-6ab21f0e7d3c"],"description":"Companies to restrict to, by `domain_search_id`."},"is_include_metadata":{"type":"boolean","example":true,"description":"Return the full detail payload. API-key traffic is lean by default: the `model` block, the confidence figures (`stage.confidence` on Company Expansion Detail, `confidence_score` on `other_markets[]` and on Rankings `markers[]`) and the `established_min` / `share_of_detected` / `has_known_office` fields are all omitted unless this is `true`."},"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.\n\nThis filter supports `is_enable_similarity_search`, once enabled you can enter any free text, e.g. `[\"Information Technology\"]`."},"news_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. Day boundaries follow your workspace timezone."},"job_exclude_locations":{"allOf":[{"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."}],"description":"Geographic locations to exclude from job posting results."},"is_include_established":{"type":"boolean","example":false,"description":"Include the `established` stage (long-standing operators with no active expansion signals). Defaults to false."},"advertisement_end_dates":{"type":"array","items":{"type":"string","format":"date"},"example":["2025-12-25","2025-12-25"],"description":"End date range for advertisement filtering."},"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.\n\nThis filter supports `is_enable_similarity_search`, once enabled you can enter any free text, e.g. `[\"Software\"]`."},"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_search_terms":{"type":"array","items":{"type":"string"},"example":["asus"],"description":"Keywords used to search within advertisement content or titles."},"is_enable_similarity_search":{"type":"boolean","example":true,"description":"Enable free-text matching for `verticals`, `vertical_categories`, `vertical_sub_categories` and `technologies`; those filters are dropped unless this is `true`."},"advertisement_target_locations":{"allOf":[{"type":"array","items":{"type":"string"},"example":["TW","AE","NO"],"description":"Country codes the results must target. Combines with `filter_conditions` as OR by default — a result matches if it targets any of them."}],"description":"Target geographic locations for advertisements."},"advertisement_exclude_target_locations":{"allOf":[{"type":"array","items":{"type":"string"},"example":["IS","GB","FR","IE","ES"],"description":"Country codes the results must not target. Combines with `filter_conditions` as OR by default — a result matches if it targets any of them."}],"description":"Geographic locations to exclude from advertisement targeting."}}},"responseSchema":{"type":"object","properties":{"data":{"type":"object","properties":{"markers":{"type":"array","items":{"type":"object","properties":{"direction":{"type":"string","description":"Trajectory of the stage."},"freshness":{"type":"string","description":"How recent the underlying signals are."},"stage_slug":{"type":"string","description":"Current expansion stage."},"country_code":{"type":"string","description":"Target market, ISO 3166-1 alpha-2."},"expansion_score":{"type":"integer","description":"Expansion score for this company/market pair."},"domain_search_id":{"type":"string","description":"Pubrio company identifier."}}},"description":"One row per company/market pair, ranked by expansion score."}},"description":"Result container."},"metadata":{"type":"object"}}},"example":null,"exampleRequest":null,"tags":[],"displayCostAmount":"unknown","displayCostAsset":"USD","priceDynamic":true,"priceHint":null,"priceStatus":"unknown_unparsed","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"unknown","summary":"price unknown","primary":{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"},"accepted":[{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"}]},"paymentMethods":[{"uid":"pm_nW886EukxLemvPQ4SN5E6","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"unknown","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":"agents.pubrio.com","brandSlug":"agents-pubrio-com-x402","brandBaseUrl":"https://agents.pubrio.com","brandDocsUrl":null,"whatItDoes":"Returns a ranked list of company/market pairs sorted by expansion score, optimized for map or heatmap visualization.","exampleAgentPrompt":"Show me a ranked list of companies expanding into Japan and South Korea — filter to those in the committing or expanding stage — so I can build a heatmap of who's moving into those markets.","exampleUseCases":[{"title":"APAC market entry heatmap","prompt":"Pull me a ranked list of companies expanding into Singapore, Japan, and South Korea — filter to expanding and scaling stages — so I can build a heatmap showing who's most aggressively entering those markets."},{"title":"Outbound sales targeting by expansion score","prompt":"Give me the top-ranked companies expanding from the US into Germany and France, filtered to fintech and SaaS keywords, so I can prioritize outreach to the ones most likely to need local services."},{"title":"Competitive landscape monitor for a specific corridor","prompt":"Which companies are expanding from India into the UK or Australia right now? Rank them by expansion score and show me their current stage so I can track the competitive landscape."}],"resultDescription":"An array of company/market pair objects each containing an expansion score (integer), expansion stage slug, target country code, trajectory direction, freshness indicator, and Pubrio company identifier — all ranked descending by expansion score. Suitable for direct rendering into map markers or heatmap cells.","failureModes":["Invalid or unrecognized stage/freshness/scope/momentum values are silently discarded, returning unfiltered results instead of an error — compare total_entries against an unfiltered call to detect this","Unrecognized signal_types or signal_strengths values cause the filter to match nothing, returning an empty result set without an error message","Missing or invalid ISO 3166-1 alpha-2 country codes may return unexpected results","Empty result sets when filters are too restrictive or no companies match the specified corridor","Truncated input schema may mean some filter combinations behave unexpectedly"],"whenToPreferThis":"Choose this endpoint when you need a lightweight, pre-ranked list of company/market pairs suitable for visualization (maps, heatmaps, league tables) rather than detailed signal evidence or full company profiles. Use it over Expansion Search when you want scores and rankings rather than paginated search results, and over Expansion Signal Search when you don't need the raw dated evidence behind each signal. It's the right choice for rendering geographic expansion activity at a glance.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-11T12:38:29.749Z","isFirstParty":false,"canonicalSlug":"agents-pubrio-com-expansion-rankings-bad0ca91"}