> ## 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.
# Cloud Footprint Search
> See which cloud and hosting providers a company runs on, in which countries and regions, and spot the markets it has just moved into.
[Cloud Footprint Search](/en/api-reference/endpoint/companies/cloud_footprints_search) returns one row per company per provider per country. A company on AWS in Germany and on Cloudflare in Singapore is two rows. Each row carries how much the company runs there, which cloud regions and cities it touches, and when that presence was first and last observed.
```bash cURL theme={null}
curl -X POST https://api.pubrio.com/companies/cloud_footprints/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target_locations": ["DE"],
"providers": ["AWS"],
"first_seen_dates": ["2026-07-01", null],
"host_count": [100, null],
"per_page": 25
}'
```
## When to use it
* **First entry.** A company's first row in a country is the moment it showed up there. `first_seen_dates` inside your window plus `is_cross_border_only` isolates exactly that.
* **Pilot or production.** A handful of hosts reads as a proof of concept; hundreds reads as a live deployment. `host_count` and `server_count` tell them apart, and a company crossing from one to the other is committing to the market.
* **New competitors.** Point `target_locations` at your own market with a recent `first_seen_dates` to see who has just arrived in it.
* **Segment by stack.** `providers` and `cloud_regions` find everyone on a given platform or in a given region.
## Scope to a company
| Key | Value |
| ------------------ | --------------------------------------------- |
| `domains` | `["stripe.com"]` |
| `domain` | `"stripe.com"` |
| `linkedin_urls` | `["https://www.linkedin.com/company/stripe"]` |
| `companies` | `["db26de04-…"]` — `domain_search_id` values |
| `domain_search_id` | `"db26de04-…"` |
A search without a company is allowed, and is the usual way to build a list — for example `{"target_locations": ["DE"], "providers": ["AWS"]}`.
## Filters
### Provider, region and city
| Key | Example |
| --------------- | -------------------------------- |
| `providers` | `["AWS", "Cloudflare"]` |
| `cloud_regions` | `["eu-central-1", "westeurope"]` |
| `cities` | `["Frankfurt", "Ashburn"]` |
Every key takes a list and has an `exclude_` twin. `cloud_regions` and `cities` are arrays on the row, so they also accept `filter_conditions` to switch from OR (any) to AND (all).
### Where the infrastructure sits
| Key | Example |
| ------------------- | -------------- |
| `target_locations` | `["DE", "SG"]` |
| `company_locations` | `["US"]` |
`target_locations` is where the infrastructure runs. `company_locations` is where the company is headquartered. The two differ on exactly the rows worth looking at.
### Size
| Key | Meaning |
| --------------------- | ----------------------------------- |
| `host_count` | Hosts on this row |
| `server_count` | Distinct IP addresses |
| `shared_server_count` | Servers shared with other companies |
| `region_count` | Cloud regions |
| `city_count` | Cities |
All five take `[min, max]`, and `null` leaves a bound open. They describe this row alone — one provider in one country.
### When it appeared
| Key | Example |
| ------------------ | ---------------------- |
| `first_seen_dates` | `["2026-07-01", null]` |
| `last_seen_dates` | `[null, "2026-06-30"]` |
Both take `[from, to]` as ISO dates, and `null` opens either end. `first_seen_dates` is the market-entry filter; `last_seen_dates` answers the opposite question.
### Cross-border only
Set `is_cross_border_only: true` to keep only presence outside the company's home market. Companies with no known headquarters are excluded rather than guessed at.
### The whole company
| Key | Meaning |
| -------------------------------------------- | --------------------------------- |
| `cloud_footprint_host_count` | Hosts everywhere |
| `cloud_footprint_provider_count` | Distinct providers used |
| `cloud_footprint_country_count` | Countries hosted in |
| `cloud_footprint_cross_border_country_count` | Countries outside the home market |
| `cloud_footprint_providers` | Uses any of these providers |
| `cloud_footprint_primary_provider` | Largest provider is one of these |
Keys prefixed `cloud_footprint_` describe the company across every row it has, not the row in front of you. Use them to qualify the company while still seeing all of its rows.
### Paging and order
`per_page`, `page` and `is_ascending_order` behave as on every search. Rows are ordered by `last_seen_at`, most recently observed first.
## What a row looks like
```json theme={null}
{
"cloud_footprint_id": "b8fcf5c3-a309-4052-ae8f-fe5706051617",
"domain_search_id": "db26de04-4131-493a-904b-2c7fda2873ee",
"provider": "Azure",
"country_code": "NL",
"company_country_code": "DK",
"is_home_market": false,
"host_count": 437,
"server_count": 8,
"shared_server_count": 0,
"region_count": 1,
"city_count": 0,
"cloud_regions": ["westeurope"],
"cities": null,
"first_seen_at": "2026-07-27T06:59:38.260Z",
"last_seen_at": "2026-09-04T12:43:28.724Z",
"evidence_url": "https://www.pubrio.com/evidence/e458a89952ed1e39e977794327939397",
"companies": {
"domain_search_id": "db26de04-4131-493a-904b-2c7fda2873ee",
"company_name": "Wonderful Sound for All - WSA",
"domain": "wsa.com",
"country_code": "DK",
"logo_url": "https://buckets.pubrio.com/company-logo/…"
}
}
```
This is a Danish company running Azure in the Netherlands: `company_country_code` is `DK`, `country_code` is `NL`, so `is_home_market` is `false`. `evidence_url` is a Pubrio page backing the row; it is `null` for a home market, which raises no expansion signal.
## Recipes
```bash cURL theme={null}
curl -X POST https://api.pubrio.com/companies/cloud_footprints/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target_locations": ["DE"],
"first_seen_dates": ["2026-08-01", null],
"is_cross_border_only": true,
"host_count": [50, null],
"per_page": 25
}'
```
```bash cURL theme={null}
curl -X POST https://api.pubrio.com/companies/cloud_footprints/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"providers": ["AWS"],
"target_locations": ["SG", "JP", "IN"],
"server_count": [10, null],
"per_page": 25
}'
```
```bash cURL theme={null}
curl -X POST https://api.pubrio.com/companies/cloud_footprints/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"cloud_footprint_country_count": [5, null],
"target_locations": ["DE"],
"host_count": [100, null],
"per_page": 25
}'
```
Each row's `domain_search_id` is a company running in at least five countries with a real deployment in this one.
```bash cURL theme={null}
curl -X POST https://api.pubrio.com/companies/cloud_footprints/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"is_cross_border_only": true,
"first_seen_dates": ["2026-08-01", null],
"host_count": [1, 25],
"per_page": 25
}'
```
A small, brand-new footprint in a market the company is not headquartered in — the shape of a proof of concept before it becomes a deployment.
## Per-company view
[Cloud Footprint Insights](/en/api-reference/endpoint/companies/cloud_footprints_insights) takes one `domain_search_id` and returns the whole picture for that company: totals, its leading providers, countries and regions, a weekly series of newly observed infrastructure, and the most recent additions. Use it for a company detail page; use search to build a list.
## Watch for changes
Cloud footprint changes surface as expansion signals, so a monitor can push them to a webhook or an email as they happen. `DNS` is the cloud footprint signal type:
```json theme={null}
{
"signal_types": ["expansions"],
"signal_filters": [
{ "signal_type": "expansions", "filters": { "tos": ["DE"], "signal_types": ["DNS"], "window_days": 30 } }
]
}
```
Every delivery carries `evidence_url`. Raw infrastructure detail is never included. See [Setting up webhooks](/en/developer-guides/setting-up-webhooks).
## Things worth knowing
* A company that runs in two countries counts in both country breakdowns, so the breakdowns can sum to more than the totals. That is per-market truth, not double counting.
* `is_cross_border` is `null` when the company has no known headquarters — that is unknown, not domestic.
* Ranges take `[min, max]` and accept `null` on either side for an open bound.
* From company search, `cloud_footprint_country_activity` scopes bounds to one country (`{"country":"DE","host_count":[100,null]}`); the flat `cloud_footprint_host_count` is the company total and cannot express that.
## Related
Every parameter and response field.
Totals, providers, regions and weekly change for one company.
Find companies by their cloud footprint on Company Search.
Push cloud footprint changes to a webhook or email.