> ## 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 Insights > Read one company's whole cloud footprint in a single call, plus flags for the changes worth acting on: moved hosts, new clouds, new regions and test environments. [Cloud Footprint Insights](/en/api-reference/endpoint/companies/cloud_footprints_insights) takes one company and returns its whole cloud footprint: totals, its top providers, countries and regions, how many new hosts appeared each week, the latest hosts, and **flags** — the changes worth acting on. Use [Cloud Footprint Search](/en/developer-guides/search/cloud-footprint-search) to build a list of companies. Use Insights when you want the full story for one of them. ## Before you start You need the company's `domain_search_id`. Every row from Cloud Footprint Search, Company Search and Company Lookup carries 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 '{ "domains": ["platform9.com"], "per_page": 1 }' ``` Take `domain_search_id` from the first row. ## Request ```bash cURL theme={null} curl -X POST https://api.pubrio.com/companies/cloud_footprints/insights \ -H "pubrio-api-key: $PUBRIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain_search_id": "a8064391-03c6-4ed2-91b0-217a9f89d418" }' ``` | Key | Required | Meaning | | - | - | - | | `domain_search_id` | Yes | The company. | | `date_from` | No | Start of the date window, `YYYY-MM-DD`. | | `date_to` | No | End of the date window, `YYYY-MM-DD`. | With no dates, the window is the last 90 days. Your plan may limit how far back `date_from` can go. ## What comes back | Key | What it is | Follows the date window? | | - | - | - | | `totals` | Hosts, servers, providers, countries, cross-border countries and regions | Only `new_hosts` | | `providers` | Top 8 providers | No | | `countries` | Top 8 countries, each with an `evidence_url` | No | | `regions` | Top 8 cloud regions | No | | `weekly_series` | Hosts first seen each week | Yes | | `recent_hosts` | Up to 12 newest hosts, one entry per host | Yes | | `window_days` | Days in the window, counting both ends | — | | `flags` | Changes worth acting on | Yes | A **host** is a named address the company runs, such as `api.example.com`. A **server** is a distinct IP address behind those hosts. The top lists are sorted by servers, then hosts. `weekly_series` weeks start on Monday in your workspace timezone. ## Flags Flags turn the footprint into things you can act on. There are five lists. Each holds up to 8 items, newest first, and each item names real hosts you can check yourself. | Flag | What it means | Why it matters | | - | - | - | | `moved_hosts` | A host now answers from a different provider, country or region. | The company is migrating or relocating. | | `twin_hosts` | The same service runs on two clouds at once, and one of them was added recently. | A multi-cloud rollout or a migration in progress. | | `test_hosts` | A new dev, test, staging or proof-of-concept host on a cloud that is not the company's main one. | The company is trying out a new cloud. This is the earliest sign. | | `new_providers` | A provider the company had not used before. | A new vendor relationship. | | `new_regions` | A new region, or a new country, on a provider the company already used. | Growth into a new geography. | Every flag is checked again when you ask for it. A change that has since been undone drops out. ### Moved hosts ```json theme={null} { "host": "onemindservices-new-jersey-prod.app.pcd.platform9.com", "is_provider_change": true, "from": { "provider": "AWS", "country_code": "US", "cloud_region": "us-west-2", "city": "Portland", "region_name": "Oregon", "first_seen_at": "2026-07-22T12:07:12.918787", "last_seen_at": "2026-07-22T12:19:41.499986" }, "to": { "provider": "OCI", "country_code": "US", "cloud_region": "us-phoenix-1", "city": "Phoenix", "region_name": "Phoenix", "first_seen_at": "2026-09-13T16:07:26.248556", "last_seen_at": "2026-09-14T09:41:19.500363" }, "is_live_confirmed": true } ``` This production host left AWS in Oregon and now runs on Oracle Cloud in Phoenix. * `is_provider_change` is `true` when the provider changed. It is `false` when only the country or region changed. * `is_live_confirmed` is `true` when the host answers from `to` right now. It is `false` when the host has left `from` but its new place could not be confirmed. ### Twin hosts ```json theme={null} { "service": "du.testbed.only.app.pcd", "providers": ["AWS", "OCI"], "new_provider": "AWS", "first_seen_at": "2026-07-21T11:59:25.286744", "new_provider_first_seen_at": "2026-09-10T09:23:35.767165", "hosts": [ { "host": "test-du-testbed-only-5113915.app.qa-pcd.platform9.com", "provider": "AWS", "country_code": "US", "cloud_region": "us-west-2", "city": "Portland", "region_name": "Oregon", "first_seen_at": "2026-09-10T09:23:35.767165" }, { "host": "test-du-testbed-only-5114083.app.qa-pcd.platform9.com", "provider": "OCI", "country_code": "US", "cloud_region": "us-phoenix-1", "city": "Phoenix", "region_name": "Phoenix", "first_seen_at": "2026-09-10T11:53:10.757998" } ] } ``` * `service` is the name the hosts share. * `providers` lists the clouds the service is live on, newest first. `new_provider` is the newest one. * `hosts` gives one live host per cloud, up to 3. ### Test hosts ```json theme={null} { "host": "iam-dev.platform.ea.com", "tags": ["dev"], "is_poc": false, "primary_provider": "AWS", "first_seen_at": "2026-09-06T08:13:54.048967", "places": [ { "provider": "GCP", "country_code": "US", "cloud_region": "us-central1", "city": "Council Bluffs", "region_name": "Iowa" } ] } ``` An AWS company with a new development host on Google Cloud. * `tags` are the words in the host name that mark it as non-production. * `is_poc` is `true` when the name marks a proof of concept or pilot. These items come first. * `places` is where the host is live now. It never includes `primary_provider`. ### New providers ```json theme={null} { "provider": "Equinix Metal", "first_seen_at": "2026-09-14T02:08:27.707494", "host_count": 1, "hosts": [ { "host": "hnjobs.cncf.io", "provider": "Equinix Metal", "country_code": "US", "cloud_region": null, "city": "Parsippany", "region_name": null, "first_seen_at": "2026-09-14T02:08:27.707494" } ] } ``` * `host_count` is how many hosts the company has on this provider now. * `hosts` gives up to 3 live hosts as proof. ### New regions ```json theme={null} { "provider": "AWS", "country_code": "US", "cloud_region": "us-west-1", "city": "San Jose", "region_name": "N. California", "first_seen_at": "2026-09-09T22:44:04.868704", "host_count": 1, "hosts": [ { "host": "mx.experience.zoom.us", "provider": "AWS", "country_code": "US", "cloud_region": "us-west-1", "city": "San Jose", "region_name": "N. California", "first_seen_at": "2026-09-09T22:44:04.868704" } ] } ``` The provider was already in use before the window. Only the region is new. When `cloud_region` is `null`, the flag is a new country on that provider. ### When flags are empty * **`flags` is `null`.** Flags are not ready for this company yet. The rest of the response is still complete. * **One list is `null`.** That list could not be built on this call. The other lists are still valid. Try again later. * **`is_spam_flood` is `true`.** The company's host names are too noisy to flag, so every list is empty. * **A list is `[]`.** Nothing matched in the window. `twin_hosts`, `test_hosts`, `new_providers` and `new_regions` only count something as new once Pubrio has tracked the company for 90 days, so a recently tracked company returns empty lists. ## Recipes ```bash cURL theme={null} curl -s -X POST https://api.pubrio.com/companies/cloud_footprints/insights \ -H "pubrio-api-key: $PUBRIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain_search_id": "a8064391-03c6-4ed2-91b0-217a9f89d418" }' \ | jq '.data.flags.moved_hosts[] | select(.is_provider_change) | {host, from: .from.provider, to: .to.provider}' ``` Keeps only moves between providers. Many moves off the same provider point to a migration. ```bash cURL theme={null} curl -s -X POST https://api.pubrio.com/companies/cloud_footprints/insights \ -H "pubrio-api-key: $PUBRIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain_search_id": "a8064391-03c6-4ed2-91b0-217a9f89d418", "date_from": "2026-08-01", "date_to": "2026-08-31" }' ``` `new_hosts`, `weekly_series`, `recent_hosts` and every flag now cover August only. The totals and top lists do not change. ```bash cURL theme={null} curl -s -X POST https://api.pubrio.com/companies/cloud_footprints/insights \ -H "pubrio-api-key: $PUBRIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain_search_id": "a8064391-03c6-4ed2-91b0-217a9f89d418" }' \ | jq '.data.flags | if . == null then "not ready" else with_entries(select(.value | type == "array") | .value |= length) end' ``` A quick check to see which flags have something before you read the details. ## Things worth knowing * A company that runs in two countries counts in both country entries, so the top lists can add up to more than `totals`. * `is_cross_border` is `null` when the company has no known headquarters. That means unknown, not domestic. ## Related Every request key and response field. Build a list of companies by provider, country, region and size. Push cloud footprint changes to a webhook or email.