- Auth: API key (Authentication)
- Scope:
companies:read - Cost: 1 credit per store found; free again within 7 days.
include=historycosts 1 more.
Use it when you have a domain and want everything we know about that store. To find stores, start from an app with GET /v1/apps/{slug}/companies.
The apps a store ran at its latest healthy scan, with its theme, country and currency. domain is
normalized (scheme, www., path and port are dropped), so https://www.allbirds.com/ works.
Costs 1 credit, free again within 7 days. A 404 (no store found) is free up to 2 × your lookups
that found a store in the last 30 days + 100, then costs 1 credit (X-Credits-Charged on the 404;
a 402 when out of credits). Until your account has bought credits, a domain we know of but have not
scanned yet answers with the same 404 as one we have never heard of. include=history adds the store's install
and removal events (history, newest first, up to 500) for 1 credit more. Scope companies:read.
Request
curl "https://api.installgraph.com/v1/companies/example.com" \
-H "Authorization: Bearer $INSTALLGRAPH_API_KEY"
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
domain |
string | Yes | Example: allbirds.com. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
include |
string | No | One of history. |
Response
200. The example's stores are fictional.
{
"data": {
"domain": "example.com",
"name": "Example Apparel Co.",
"myshopifyDomain": "example-apparel.myshopify.com",
"country": "US",
"region": "north-america",
"industry": {
"category": "Apparel",
"subcategory": "Footwear",
"path": "/Apparel/Footwear",
"confidence": "high"
},
"pricePoint": {
"aovBand": "100-200",
"label": "$100–200",
"confidence": "medium",
"medianProductPriceUsd": 128,
"productPriceRangeUsd": [
95,
165
],
"productPricesSeen": 24
},
"currency": "USD",
"locale": "en",
"status": "live",
"theme": {
"name": "Dawn",
"version": "15.2.0",
"themeStoreId": 887,
"customName": "Dawn - spring",
"since": "2026-03-02T04:11:09.000Z"
},
"lastScannedAt": "2026-11-02T03:40:12.000Z",
"lastHealthyScanAt": "2026-11-02T03:40:12.000Z",
"customPixelCount": 2,
"apps": [
{
"slug": "klaviyo",
"name": "Klaviyo",
"category": "email-sms",
"firstSeenAt": "2026-01-12T05:02:44.000Z",
"lastSeenAt": "2026-11-02T03:40:12.000Z",
"evidence": [
"webPixel",
"themeAppExtension"
]
},
{
"slug": "judge-me",
"name": "Judge.me",
"category": "reviews",
"firstSeenAt": "2026-01-12T05:02:44.000Z",
"lastSeenAt": "2026-11-02T03:40:12.000Z",
"evidence": [
"themeAppExtension",
"script"
]
}
]
},
"meta": {
"requestId": "6f1c2a9e-4b7d-4e2a-9c51-0d3b8e7f2a14",
"creditsUsed": 1,
"creditsCharged": 1,
"creditsRemaining": 49,
"freeRepulls": 0
}
}
Fields
| Field | Type | Description |
|---|---|---|
data.domain |
string | Example: allbirds.com. |
data.name |
string | null | |
data.myshopifyDomain |
string | null | Example: allbirds.myshopify.com. |
data.country |
string | null | Example: US. |
data.region |
Region | null | One of north-america, latin-america, europe, middle-east-africa, asia-pacific. |
data.industry |
Industry | null | Our reading of what the store sells, from its homepage, in the Store Leads taxonomy. |
data.industry.category |
string | Example: Apparel. |
data.industry.subcategory |
string | null | Null when the store fits a category but none of its subcategories (a general bookshop). Example: Footwear. |
data.industry.path |
string | /Books & Literature alone when there is no subcategory. Example: /Apparel/Footwear. |
data.industry.confidence |
string | null | One of high, medium, low. |
data.pricePoint |
PricePoint | null | The store's typical order value, in USD bands so it reads the same in every country. Our own reading of the homepage: the product prices shown there (converted from the store's currency), and what is sold. |
data.pricePoint.aovBand |
string | One of under-25, 25-50, 50-100, 100-200, 200-500, 500-1000, 1000-plus. |
data.pricePoint.label |
string | Example: $100–200. |
data.pricePoint.confidence |
string | null | One of high, medium, low. |
data.pricePoint.medianProductPriceUsd |
integer | null | Median product price on the homepage, in USD. |
data.pricePoint.productPriceRangeUsd |
integer[] | null | Interquartile range of homepage product prices, in USD. |
data.pricePoint.productPricesSeen |
integer | |
data.currency |
string | null | Example: USD. |
data.locale |
string | null | Example: en. |
data.status |
Status | The latest scan's verdict: live, password (behind a password page), closed (store unavailable), not_shopify (the domain no longer serves a Shopify store), or unreachable (we could not read the page this time). Apps are from the latest live scan (lastHealthyScanAt). One of live, password, closed, not_shopify, unreachable. |
data.theme |
object | null | |
data.theme.name |
string | The theme's own name (schema name), e.g. Dawn. |
data.theme.version |
string | null | |
data.theme.themeStoreId |
integer | null | Shopify Theme Store id, for a store theme. |
data.theme.customName |
string | null | What the merchant named their copy. |
data.theme.since |
string (date-time) | null | First scan on this theme. |
data.lastScannedAt |
string (date-time) | |
data.lastHealthyScanAt |
string (date-time) | null | |
data.customPixelCount |
integer | null | Custom pixels in Shopify's Customer events. |
data.apps |
CompanyApp[] | |
data.apps[].slug |
string | Example: klaviyo. |
data.apps[].name |
string | Example: Klaviyo. |
data.apps[].category |
Category | One of 28 values (see Data model). |
data.apps[].kind |
string | shopify-app: an app installed from Shopify. web: a website technology installed outside Shopify, by pasting its tag into the theme or through a tag manager (Google Tag Manager, Meta Pixel, Hotjar). A vendor with both has one entry of each (meta-pixel and meta-facebook-instagram-app). One of shopify-app, web. |
data.apps[].firstSeenAt |
string (date-time) | First scan that found it. |
data.apps[].lastSeenAt |
string (date-time) | Latest scan that found it. |
data.apps[].evidence |
Evidence[] | One of webPixel, themeAppExtension, appProxy, customPixel, script, html. |
Every keyed response also carries meta (requestId, creditsUsed, creditsRemaining, freeRepulls) and the X-Credits-* and X-RateLimit-* headers. See Credits and Rate limits.
Errors
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_request |
A parameter or body field is missing or malformed. | Fix the request; message names the field. Do not retry unchanged. |
| 401 | missing_api_key |
No key was sent. | Send Authorization: Bearer sfs_… or X-API-Key: sfs_…. |
| 401 | invalid_api_key |
The key is not one we issued. | Check for truncation or whitespace; keys are sfs_ plus 32 letters and digits. |
| 401 | api_key_revoked |
The key was revoked. | Make a new key at installgraph.com/account. |
| 402 | insufficient_credits |
The balance cannot cover one row or lookup. Nothing was charged. | Buy credits: error.offers.pack.buyUrl, or POST /v1/billing/purchase if agent purchases are on. |
| 402 | usage_cap_reached |
The account unlocked 40,000 distinct stores in the last 30 days. | Wait for the window to roll, or Talk to us: error.offers.talkToUs.url. |
| 403 | insufficient_scope |
The key lacks this endpoint's scope. | Use a key with the scope the endpoint lists (GET /v1/usage shows yours). |
| 403 | api_key_suspended |
The key is suspended. | Talk to us, quoting requestId. |
| 404 | not_found |
No such endpoint, app, or store (or not scanned yet). | Check the slug or domain. Store 404s are free within the lookup-miss allowance. |
| 429 | rate_limited |
Too many requests this minute. | Wait Retry-After seconds, then retry. |
All codes: Errors.