Pricing

REST endpoints for Pricing. Base URL https://api.competlab.com; every request needs a CL-API-Key header (see Authentication). Responses wrap in { item } or { items }; errors in { error }.

Get latest pricing intelligence data

GET/v1/projects/{projectId}/pricing

Get the latest pricing intelligence data for all competitors in a project. Returns structured pricing plans, free tier availability, billing options, enterprise pricing, promotions, and competitive gap analysis. Every tracked competitor appears — rows without pricing data carry a pricingDataAvailable reason (no pricing page found, their page didn’t respond, or a temporary problem on our side) instead of being omitted; branch on it before quoting pricing facts. A pricing page is the single most likely thing to be missing, so this is the dimension where the null contract matters most: when your own pricing couldn’t be analyzed, every metric on summary.customer is null and pricingAnalysisAvailable says why. hasFreePlan: null means we did not check, NOT that there is no free plan — a measured false is reported as false and is a real finding. The three gap flags do NOT share one null condition, so read each field’s own description rather than gating all three on the same test: all three are null when your side was unmeasured or no competitor was measured, and hasPriceGap is null on two further conditions the other two don’t carry — fewer than three comparable competitor prices, or your own price not being comparable to the market. Market figures (marketAvgPrice, pricePositionPercent) are null below that three-price threshold, which is ‘not enough market to average’, never zero. Comparable means fixed monthly amounts sharing one currency AND one licensed unit: a per-seat price is never averaged against a flat one, marketPricingUnit says which group was chosen, and every market figure must be quoted with it. A project with no completed run for this dimension yet answers 404 no_data_available — not a missing project and not a failed measurement, just nothing measured here so far; the project itself is fine and get_project still describes it. Distinguish it from project_not_found, which means the id is wrong.

Returns · { item }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/pricing" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "item": {
    "lastUpdatedAt": "2026-03-15T10:00:00.000Z",
    "summary": {
      "competitorsChecked": 6,
      "competitorsSuccessful": 5,
      "customer": {
        "domain": "yoursite.com",
        "popularPlanPrice": 49,
        "popularPlanCurrency": "USD",
        "popularPlanUnit": "flat",
        "popularPlanName": "Professional",
        "pricingModel": "per-seat",
        "hasFreePlan": false,
        "hasFreeTrial": true,
        "freeTrialDuration": "14 days",
        "hasEnterprisePricing": true,
        "tierCount": 3,
        "pricingAnalysisAvailable": {
          "available": false,
          "reason": "pricing_fetch_failed"
        }
      },
      "marketAvgPrice": 59,
      "marketCurrency": "USD",
      "marketPricingUnit": "flat",
      "pricePositionPercent": 45,
      "topPriceCompetitor": {
        "domain": "rival.com",
        "price": 99,
        "planName": "Enterprise"
      },
      "lowestPriceCompetitor": {
        "domain": "rival.com",
        "price": 99,
        "planName": "Enterprise"
      },
      "pricingSampleSize": 4,
      "pricingIsReliable": true,
      "competitorsWithFreePlan": 2,
      "competitorsWithFreeTrial": 4,
      "competitorsWithEnterprise": 3,
      "activePromotionCount": 1,
      "hasPriceGap": true,
      "hasFreeTierGap": false,
      "hasEnterpriseGap": false,
      "hasPromotionAlert": true
    },
    "competitors": [
      {
        "domain": "competitor.com",
        "isOwn": false,
        "pricingUrl": "https://competitor.com/pricing",
        "pricingLocationType": "crawled",
        "content": {
          "pageTitle": "Acme Pricing - Plans for Every Team",
          "pageDescription": "Choose from flexible pricing plans starting at $9/month.",
          "mainHeadline": "Simple, Transparent Pricing",
          "pricingModel": "per-seat",
          "plans": [
            {
              "name": "Professional",
              "price": "$49/month",
              "summary": "Best for growing teams with advanced features"
            }
          ],
          "popularPlanName": "Professional",
          "hasFreePlan": true,
          "freePlanName": "Starter",
          "hasFreeTrial": true,
          "freeTrialDuration": "14 days",
          "billingCycleOffered": "monthly, annual",
          "annualDiscountAmount": "20%",
          "moneyBackGuarantee": "30-day money-back guarantee",
          "hasEnterpriseCustomPricing": true,
          "enterprisePlanCTA": "Contact Sales",
          "pricingPageFeatures": "Unlimited projects, Priority support, SSO",
          "hasActivePromotion": false,
          "promotionDetails": ""
        },
        "pricingDataAvailable": {
          "available": false,
          "reason": "no_page_found"
        }
      }
    ]
  }
}

Fields

item — object

Field	Type	Description
`lastUpdatedAt`	`string`	When this data was last updated (ISO-8601)
`summary`	`object`	Run summary with pricing gap analysis. See `item.summary`.
`competitors`	`array<object>`	Per-competitor pricing data. Every competitor tracked by the project appears, your own domain included — rows without pricing data carry `pricingDataAvailable` saying why instead of being dropped. Competitor rows show the most recent successful read (which may predate the latest run); your own row reflects the latest completed check. See `item.competitors[]`.

item.summary — object

Field	Type	Description
`competitorsChecked`	`number`	Number of competitor pricing pages checked
`competitorsSuccessful`	`number`	Number of competitor pricing pages successfully analyzed
`customer`	`object`	Your pricing metrics. See `item.summary.customer`.
`marketAvgPrice`	`number \| null`	Market average price (numeric, in `marketCurrency`, per `marketPricingUnit`). Only comparable competitor prices are averaged: fixed monthly recurring amounts sharing BOTH that currency and that licensed unit — your own price is never included. Usage-based prices (per-GB, per-request, hourly), one-time prices, prices in other currencies, and prices in a different licensed unit are never averaged; no currency conversion and no unit mixing is ever performed, so a per-seat price and a flat monthly price never land in the same average. Null when fewer than 3 comparable competitor prices exist — treat null as ‘not enough comparable market data’, never as zero. Always quote it with its unit: ‘$59 per seat per month’ and ‘$59 per month’ are different claims. Data recorded before unit grouping existed carries no `marketPricingUnit` and its average may mix units — check for that field’s absence before quoting a historical figure. Nullable.
`marketCurrency`	`string \| null`	The currency all market figures are computed in — the majority currency among comparable competitor prices (a tie prefers your own). Together with `marketPricingUnit` it sets `marketAvgPrice`, `pricePositionPercent`, `topPriceCompetitor`, `lowestPriceCompetitor`, and which prices count toward `pricingSampleSize`. Prices in other currencies stay visible on their rows but are excluded. Null when no comparable competitor price exists, or on data recorded before currency capture existed. Nullable.
`marketPricingUnit`	`string \| null`	The licensed unit all market figures are computed in — ‘flat’ for plain monthly amounts, or ‘per-seat’ / ‘per-license’ / similar for per-unit monthly licensing. It is the majority unit among the comparable competitor prices already sharing `marketCurrency` (a tie prefers your own), and it is the second half of what makes a market figure comparable: competitors pricing in a different unit stay visible on their rows but are excluded from every market figure, because averaging ‘$15 per seat per month’ with ‘$475 per month’ describes no market that exists. Null when no comparable competitor price exists. ABSENT on data recorded before unit grouping existed — on that data the market figures were averaged across mixed units, so the absence of this field is your signal not to quote them as a like-for-like market price. Nullable.
`pricePositionPercent`	`number \| null`	Your price position vs market average (percent; negative = below market). Null when `marketAvgPrice` is null, and ALSO null whenever your own price isn’t comparable to the market — a different currency (no conversion is ever performed), a different licensed unit (compare `popularPlanUnit` with `marketPricingUnit`), or non-monthly pricing. Treat null as ‘no comparable position’, never as 0%. Nullable.
`topPriceCompetitor`	`object \| null`	Competitor with the highest comparable price (fixed monthly, in `marketCurrency`, per `marketPricingUnit`). Descriptive, not a market verdict: present at any sample size — caption it with `pricingSampleSize`. Null when no comparable competitor price exists. A competitor priced in another currency or another unit may well charge more and still not appear here. Data recorded before this change stored null whenever `pricingIsReliable` was false. Nullable. See `item.summary.topPriceCompetitor`.
`lowestPriceCompetitor`	`object \| null`	Competitor with the lowest comparable price (fixed monthly, in `marketCurrency`, per `marketPricingUnit`). Same semantics as `topPriceCompetitor` — descriptive at any sample size, null when no comparable competitor price exists. Nullable. See `item.summary.lowestPriceCompetitor`.
`pricingSampleSize`	`number`	Number of competitor prices comparable enough to aggregate: fixed monthly recurring amounts sharing both `marketCurrency` and `marketPricingUnit`, your own domain always excluded. This is the honest denominator behind `marketAvgPrice`. Competitors with usage-based, one-time, other-currency, or other-unit pricing don’t count here — their pricing model is still visible on their rows, and a low number here usually means the market prices in several different ways rather than that we failed to read it. On data recorded before this change, this counted any numeric price regardless of unit or currency.
`pricingIsReliable`	`boolean`	True when `pricingSampleSize` >= 3 — enough comparable competitor prices for market-average and position claims. When false, `marketAvgPrice`, `pricePositionPercent` and `hasPriceGap` are all null: there is no market average to sit above, so there is no verdict either. `topPriceCompetitor` / `lowestPriceCompetitor` remain as descriptive data points.
`competitorsWithFreePlan`	`number`	Number of competitors offering a free plan
`competitorsWithFreeTrial`	`number`	Number of competitors offering a free trial
`competitorsWithEnterprise`	`number`	Number of competitors with enterprise pricing
`activePromotionCount`	`number`	Number of competitors running active promotions
`hasPriceGap`	`boolean \| null`	Whether you sit 20%+ above the market average. `false` means measured, with no gap. Null in three cases, all of them ‘we couldn’t make the comparison’: your own pricing wasn’t measured this run; `pricingIsReliable` is false (too few comparable competitor prices to establish a market average); or `pricePositionPercent` is null because your own price isn’t comparable to the market — a different currency, a different licensed unit, or usage-based rather than a fixed monthly amount. That is a WIDER set of null conditions than the other two gap flags carry, so check this field’s own list rather than assuming all three null together. Never read a null as ‘no gap’. Nullable.
`hasFreeTierGap`	`boolean \| null`	Whether at least half of your tracked competitors offer a free tier and you don’t. `false` means measured, with no gap. Null when either side of the comparison is missing — those are its only two null conditions: your own pricing wasn’t measured this run, or no competitor was measured at all (with no market there is no majority to be behind). It does NOT null on a thin comparable-price sample, because free-tier availability doesn’t depend on prices being comparable: a `false` here alongside a null `hasPriceGap` is consistent, not contradictory. Read `competitorsWithFreePlan` alongside it. Nullable.
`hasEnterpriseGap`	`boolean \| null`	Whether competitors offer enterprise pricing and you don’t. Null when either side of the comparison is missing — your own pricing unmeasured, or no competitor measured. Those are its only two null conditions; like `hasFreeTierGap`, and unlike `hasPriceGap`, it does not null on a thin comparable-price sample. `false` means measured, with no gap. Nullable.
`hasPromotionAlert`	`boolean`	Whether competitors are running promotions you should know about

item.competitors[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`isOwn`	`boolean`	Whether this is the project’s own domain
`pricingUrl`	`string \| null`	Pricing page URL that was analyzed, or null exactly when `pricingDataAvailable` is present (no pricing data on this row). Nullable.
`pricingLocationType`	`string \| null`	How the pricing page was located, or null exactly when `pricingDataAvailable` is present. Nullable.
`content`	`object \| null`	Extracted pricing page content, or null exactly when `pricingDataAvailable` is present. A null here means this competitor’s pricing is unmeasured — never ‘they offer no pricing’. Nullable. See `item.competitors[].content`.
`pricingDataAvailable`	`object`	Present ONLY when this row has no pricing data — `reason` says why. When present, `pricingUrl`, `pricingLocationType`, and `content` are null: branch on this field before quoting any price, plan, or pricing fact from the row. Absent on measured rows, including every response from before this field existed. On the dashboard, competitor rows keep their most recent successful read, so this marker appears only for a competitor never read successfully — its `reason` reflects the latest completed check. Your own row is different: it always reflects the latest completed check, success or failure. In run-detail responses the marker is scoped to that run. See `item.competitors[].pricingDataAvailable`.

item.summary.customer — object

Field	Type	Description
`domain`	`string`	Your domain. Unlike every other field here it is not nulled when nothing was measured, because it stays a known fact — it is read from your project’s own configuration, not from the pricing check. The one exception is a project with no own-domain entry on file at all, where there is no domain to report and this carries the literal placeholder `unknown`. That string is a marker, never a domain: don’t render it, resolve it, or describe it as a site.
`popularPlanPrice`	`number \| null`	The price of the plan named by `popularPlanName` — which is not always the plan you badge as most popular; see that field. Null if unavailable. Check `popularPlanCurrency` before rendering a currency symbol next to it — this amount is in whatever currency your pricing page uses, not necessarily USD — and `popularPlanUnit` before describing it, since it may be priced per seat rather than flat. Nullable.
`popularPlanCurrency`	`string \| null`	Currency of `popularPlanPrice` as read off your pricing page — ‘USD’ / ‘EUR’ / ‘GBP’, or the verbatim currency symbol for other currencies. Null when no currency could be detected on the page, or on data recorded before currency capture existed — never treat null as USD. Nullable.
`popularPlanUnit`	`string \| null`	The licensed unit your popular plan price is quoted in — ‘flat’ for a plain monthly amount, or ‘per-seat’ / ‘per-license’ / similar for per-unit monthly licensing. Null when your price isn’t a comparable monthly amount at all (usage-based, one-time, or unreadable), and absent on data recorded before unit capture existed — never treat either as ‘flat’. Compare it with `marketPricingUnit`: when the two differ, `pricePositionPercent` is null because a per-seat price and a flat price are not the same kind of number, however similar the figures look. Nullable.
`popularPlanName`	`string \| null`	The plan we use to represent your pricing: your own ‘most popular’ badge when that plan lists a comparable monthly price, otherwise the cheapest plan on your page that does — a free or quote-only flagship carries no amount to position against a market. So this is not always the plan you feature. `popularPlanPrice`, `popularPlanCurrency` and `popularPlanUnit` all describe THIS plan, whichever one it is. Null if your pricing wasn’t measured this run. Nullable.
`pricingModel`	`string \| null`	Your pricing model type, or null if unavailable. Nullable.
`hasFreePlan`	`boolean \| null`	Whether you offer a permanent free plan, or null if your own pricing wasn’t measured this run. `false` is a measured finding — we read your pricing page and there is no free plan. Never report a null as ‘no free plan’. Nullable.
`hasFreeTrial`	`boolean \| null`	Whether you offer a free trial, or null if your own pricing wasn’t measured this run. `false` is a measured finding. Nullable.
`freeTrialDuration`	`string \| null`	Free trial duration, or null if not offered or not measured. Nullable.
`hasEnterprisePricing`	`boolean \| null`	Whether you offer enterprise/custom pricing, or null if your own pricing wasn’t measured this run. `false` is a measured finding. Nullable.
`tierCount`	`number \| null`	Number of pricing tiers, or null if your own pricing wasn’t measured this run. Never read a null as 0 — ‘0 tiers’ is a claim about your pricing page, not about whether we reached it. Nullable.
`pricingAnalysisAvailable`	`object`	Availability flag for your own pricing. Present ONLY when your own pricing couldn’t be analyzed this run (fetch failed, or no pricing URL configured) — see `reason`. When present, every pricing metric in this object is `null`, and so are `pricePositionPercent` and all three gap flags (`hasPriceGap`, `hasFreeTierGap`, `hasEnterpriseGap`). Nothing here is a measured fact: report no price, market position, tier status, tier count or gap verdict. Only `domain` remains populated — and where no domain was on file it holds the literal placeholder `unknown` rather than being omitted, so treat that exact string as ‘no domain’, not as a site name. Note this flag is a sufficient reason for those nulls, never a necessary one: `hasPriceGap` and the market figures also null on a market too thin or too mixed to compare, with this flag absent. Absent on healthy runs (the normal path). See `item.summary.customer.pricingAnalysisAvailable`.

item.summary.topPriceCompetitor — object

Field	Type	Description
`domain`	`string`	Competitor domain
`price`	`number`	Price (numeric)
`planName`	`string`	Plan name

item.summary.lowestPriceCompetitor — object

Field	Type	Description
`domain`	`string`	Competitor domain
`price`	`number`	Price (numeric)
`planName`	`string`	Plan name

item.competitors[].content — object

Field	Type	Description
`pageTitle`	`string`	Page title
`pageDescription`	`string`	Page meta description
`mainHeadline`	`string`	Main pricing page headline
`pricingModel`	`string`	Pricing model type
`plans`	`array<object>`	Structured pricing plans extracted from the page. See `item.competitors[].content.plans[]`.
`popularPlanName`	`string`	Name of the recommended/popular plan
`hasFreePlan`	`boolean`	Whether a free plan is offered
`freePlanName`	`string`	Name of the free plan if offered
`hasFreeTrial`	`boolean`	Whether a free trial is offered
`freeTrialDuration`	`string`	Free trial duration if offered
`billingCycleOffered`	`string`	Billing cycles offered
`annualDiscountAmount`	`string`	Annual discount amount if offered
`moneyBackGuarantee`	`string`	Money-back guarantee details
`hasEnterpriseCustomPricing`	`boolean`	Whether enterprise/custom pricing is available
`enterprisePlanCTA`	`string`	Enterprise plan CTA text
`pricingPageFeatures`	`string`	Key features listed on pricing page (comma-separated)
`hasActivePromotion`	`boolean`	Whether an active promotion is running
`promotionDetails`	`string`	Promotion details if active

item.competitors[].pricingDataAvailable — object

Field	Type	Description
`available`	`boolean`	Always false — present only when this row carries no pricing data
`reason`	`string`	Why this row has no pricing data. ‘no_page_found’ = we didn’t find a pricing page for this competitor — they may simply not publish one; if you know the URL, adding it in competitor settings enables this check. ‘fetch_failed_their_side’ = their pricing page didn’t respond to this check (blocked, errored, or timed out) — nothing was measured. ‘fetch_failed_our_side’ = a temporary problem on our side stopped this check — nothing was measured, and it says nothing about the competitor. Never turn any of these reasons into a pricing claim: a row carrying one has no price, plan, or tier facts to quote. Values: `no_page_found`, `fetch_failed_their_side`, `fetch_failed_our_side`.

item.summary.customer.pricingAnalysisAvailable — object

Field	Type	Description
`available`	`boolean`	Always false for this discriminator.
`reason`	`string`	Why your own pricing couldn’t be analyzed. ‘pricing_fetch_failed’ = we couldn’t retrieve your pricing page this run; ‘pricing_url_not_configured’ = no pricing URL is set for your own domain. Values: `pricing_fetch_failed`, `pricing_url_not_configured`.

item.competitors[].content.plans[] — each entry

Field	Type	Description
`name`	`string`	Plan name
`price`	`string`	Plan price
`summary`	`string`	Brief summary of the plan

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
404	`project_not_found` · `no_data_available`	No `project` matches the id in the path.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}

Get pricing run history

GET/v1/projects/{projectId}/pricing/history

Get paginated history of pricing intelligence monitoring runs for a project. Each entry includes run timing and summary statistics with pricing gap analysis. Fields we could not measure are null, with a sibling availability object giving the reason; never read a null as zero, false or absent, and note that a measured 0 / false / empty list is reported as itself and is a real finding.

Returns · { items, pagination }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Query parameters

Name	Type	Required	Description
`page`	`number`		Page number (1-indexed). Default `1`. Min `1`.
`limit`	`number`		Number of items per page. Default `20`. Range `1`–`100`.

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/pricing/history?page=1&limit=20" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "items": [
    {
      "runId": "507f1f77bcf86cd799439011",
      "completedAt": "2026-03-15T10:00:00.000Z",
      "summary": {
        "competitorsChecked": 6,
        "competitorsSuccessful": 5,
        "customer": {
          "domain": "yoursite.com",
          "popularPlanPrice": 49,
          "popularPlanCurrency": "USD",
          "popularPlanUnit": "flat",
          "popularPlanName": "Professional",
          "pricingModel": "per-seat",
          "hasFreePlan": false,
          "hasFreeTrial": true,
          "freeTrialDuration": "14 days",
          "hasEnterprisePricing": true,
          "tierCount": 3,
          "pricingAnalysisAvailable": {
            "available": false,
            "reason": "pricing_fetch_failed"
          }
        },
        "marketAvgPrice": 59,
        "marketCurrency": "USD",
        "marketPricingUnit": "flat",
        "pricePositionPercent": 45,
        "topPriceCompetitor": {
          "domain": "rival.com",
          "price": 99,
          "planName": "Enterprise"
        },
        "lowestPriceCompetitor": {
          "domain": "rival.com",
          "price": 99,
          "planName": "Enterprise"
        },
        "pricingSampleSize": 4,
        "pricingIsReliable": true,
        "competitorsWithFreePlan": 2,
        "competitorsWithFreeTrial": 4,
        "competitorsWithEnterprise": 3,
        "activePromotionCount": 1,
        "hasPriceGap": true,
        "hasFreeTierGap": false,
        "hasEnterpriseGap": false,
        "hasPromotionAlert": true
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "totalPages": 3,
    "hasMore": true
  }
}

Fields

items[] — each entry

Field	Type	Description
`runId`	`string`	Run ID
`completedAt`	`string`	When this run completed (ISO-8601)
`summary`	`object`	Run summary statistics. See `items[].summary`.

pagination — object

Field	Type	Description
`page`	`number`	Current page number (1-indexed)
`limit`	`number`	Number of items per page
`total`	`number`	Total number of items across all pages
`totalPages`	`number`	Total number of pages
`hasMore`	`boolean`	Whether more pages exist after the current page

items[].summary — object

Field	Type	Description
`competitorsChecked`	`number`	Number of competitor pricing pages checked
`competitorsSuccessful`	`number`	Number of competitor pricing pages successfully analyzed
`customer`	`object`	Your pricing metrics. See `items[].summary.customer`.
`marketAvgPrice`	`number \| null`	Market average price (numeric, in `marketCurrency`, per `marketPricingUnit`). Only comparable competitor prices are averaged: fixed monthly recurring amounts sharing BOTH that currency and that licensed unit — your own price is never included. Usage-based prices (per-GB, per-request, hourly), one-time prices, prices in other currencies, and prices in a different licensed unit are never averaged; no currency conversion and no unit mixing is ever performed, so a per-seat price and a flat monthly price never land in the same average. Null when fewer than 3 comparable competitor prices exist — treat null as ‘not enough comparable market data’, never as zero. Always quote it with its unit: ‘$59 per seat per month’ and ‘$59 per month’ are different claims. Data recorded before unit grouping existed carries no `marketPricingUnit` and its average may mix units — check for that field’s absence before quoting a historical figure. Nullable.
`marketCurrency`	`string \| null`	The currency all market figures are computed in — the majority currency among comparable competitor prices (a tie prefers your own). Together with `marketPricingUnit` it sets `marketAvgPrice`, `pricePositionPercent`, `topPriceCompetitor`, `lowestPriceCompetitor`, and which prices count toward `pricingSampleSize`. Prices in other currencies stay visible on their rows but are excluded. Null when no comparable competitor price exists, or on data recorded before currency capture existed. Nullable.
`marketPricingUnit`	`string \| null`	The licensed unit all market figures are computed in — ‘flat’ for plain monthly amounts, or ‘per-seat’ / ‘per-license’ / similar for per-unit monthly licensing. It is the majority unit among the comparable competitor prices already sharing `marketCurrency` (a tie prefers your own), and it is the second half of what makes a market figure comparable: competitors pricing in a different unit stay visible on their rows but are excluded from every market figure, because averaging ‘$15 per seat per month’ with ‘$475 per month’ describes no market that exists. Null when no comparable competitor price exists. ABSENT on data recorded before unit grouping existed — on that data the market figures were averaged across mixed units, so the absence of this field is your signal not to quote them as a like-for-like market price. Nullable.
`pricePositionPercent`	`number \| null`	Your price position vs market average (percent; negative = below market). Null when `marketAvgPrice` is null, and ALSO null whenever your own price isn’t comparable to the market — a different currency (no conversion is ever performed), a different licensed unit (compare `popularPlanUnit` with `marketPricingUnit`), or non-monthly pricing. Treat null as ‘no comparable position’, never as 0%. Nullable.
`topPriceCompetitor`	`object \| null`	Competitor with the highest comparable price (fixed monthly, in `marketCurrency`, per `marketPricingUnit`). Descriptive, not a market verdict: present at any sample size — caption it with `pricingSampleSize`. Null when no comparable competitor price exists. A competitor priced in another currency or another unit may well charge more and still not appear here. Data recorded before this change stored null whenever `pricingIsReliable` was false. Nullable. See `items[].summary.topPriceCompetitor`.
`lowestPriceCompetitor`	`object \| null`	Competitor with the lowest comparable price (fixed monthly, in `marketCurrency`, per `marketPricingUnit`). Same semantics as `topPriceCompetitor` — descriptive at any sample size, null when no comparable competitor price exists. Nullable. See `items[].summary.lowestPriceCompetitor`.
`pricingSampleSize`	`number`	Number of competitor prices comparable enough to aggregate: fixed monthly recurring amounts sharing both `marketCurrency` and `marketPricingUnit`, your own domain always excluded. This is the honest denominator behind `marketAvgPrice`. Competitors with usage-based, one-time, other-currency, or other-unit pricing don’t count here — their pricing model is still visible on their rows, and a low number here usually means the market prices in several different ways rather than that we failed to read it. On data recorded before this change, this counted any numeric price regardless of unit or currency.
`pricingIsReliable`	`boolean`	True when `pricingSampleSize` >= 3 — enough comparable competitor prices for market-average and position claims. When false, `marketAvgPrice`, `pricePositionPercent` and `hasPriceGap` are all null: there is no market average to sit above, so there is no verdict either. `topPriceCompetitor` / `lowestPriceCompetitor` remain as descriptive data points.
`competitorsWithFreePlan`	`number`	Number of competitors offering a free plan
`competitorsWithFreeTrial`	`number`	Number of competitors offering a free trial
`competitorsWithEnterprise`	`number`	Number of competitors with enterprise pricing
`activePromotionCount`	`number`	Number of competitors running active promotions
`hasPriceGap`	`boolean \| null`	Whether you sit 20%+ above the market average. `false` means measured, with no gap. Null in three cases, all of them ‘we couldn’t make the comparison’: your own pricing wasn’t measured this run; `pricingIsReliable` is false (too few comparable competitor prices to establish a market average); or `pricePositionPercent` is null because your own price isn’t comparable to the market — a different currency, a different licensed unit, or usage-based rather than a fixed monthly amount. That is a WIDER set of null conditions than the other two gap flags carry, so check this field’s own list rather than assuming all three null together. Never read a null as ‘no gap’. Nullable.
`hasFreeTierGap`	`boolean \| null`	Whether at least half of your tracked competitors offer a free tier and you don’t. `false` means measured, with no gap. Null when either side of the comparison is missing — those are its only two null conditions: your own pricing wasn’t measured this run, or no competitor was measured at all (with no market there is no majority to be behind). It does NOT null on a thin comparable-price sample, because free-tier availability doesn’t depend on prices being comparable: a `false` here alongside a null `hasPriceGap` is consistent, not contradictory. Read `competitorsWithFreePlan` alongside it. Nullable.
`hasEnterpriseGap`	`boolean \| null`	Whether competitors offer enterprise pricing and you don’t. Null when either side of the comparison is missing — your own pricing unmeasured, or no competitor measured. Those are its only two null conditions; like `hasFreeTierGap`, and unlike `hasPriceGap`, it does not null on a thin comparable-price sample. `false` means measured, with no gap. Nullable.
`hasPromotionAlert`	`boolean`	Whether competitors are running promotions you should know about

items[].summary.customer — object

Field	Type	Description
`domain`	`string`	Your domain. Unlike every other field here it is not nulled when nothing was measured, because it stays a known fact — it is read from your project’s own configuration, not from the pricing check. The one exception is a project with no own-domain entry on file at all, where there is no domain to report and this carries the literal placeholder `unknown`. That string is a marker, never a domain: don’t render it, resolve it, or describe it as a site.
`popularPlanPrice`	`number \| null`	The price of the plan named by `popularPlanName` — which is not always the plan you badge as most popular; see that field. Null if unavailable. Check `popularPlanCurrency` before rendering a currency symbol next to it — this amount is in whatever currency your pricing page uses, not necessarily USD — and `popularPlanUnit` before describing it, since it may be priced per seat rather than flat. Nullable.
`popularPlanCurrency`	`string \| null`	Currency of `popularPlanPrice` as read off your pricing page — ‘USD’ / ‘EUR’ / ‘GBP’, or the verbatim currency symbol for other currencies. Null when no currency could be detected on the page, or on data recorded before currency capture existed — never treat null as USD. Nullable.
`popularPlanUnit`	`string \| null`	The licensed unit your popular plan price is quoted in — ‘flat’ for a plain monthly amount, or ‘per-seat’ / ‘per-license’ / similar for per-unit monthly licensing. Null when your price isn’t a comparable monthly amount at all (usage-based, one-time, or unreadable), and absent on data recorded before unit capture existed — never treat either as ‘flat’. Compare it with `marketPricingUnit`: when the two differ, `pricePositionPercent` is null because a per-seat price and a flat price are not the same kind of number, however similar the figures look. Nullable.
`popularPlanName`	`string \| null`	The plan we use to represent your pricing: your own ‘most popular’ badge when that plan lists a comparable monthly price, otherwise the cheapest plan on your page that does — a free or quote-only flagship carries no amount to position against a market. So this is not always the plan you feature. `popularPlanPrice`, `popularPlanCurrency` and `popularPlanUnit` all describe THIS plan, whichever one it is. Null if your pricing wasn’t measured this run. Nullable.
`pricingModel`	`string \| null`	Your pricing model type, or null if unavailable. Nullable.
`hasFreePlan`	`boolean \| null`	Whether you offer a permanent free plan, or null if your own pricing wasn’t measured this run. `false` is a measured finding — we read your pricing page and there is no free plan. Never report a null as ‘no free plan’. Nullable.
`hasFreeTrial`	`boolean \| null`	Whether you offer a free trial, or null if your own pricing wasn’t measured this run. `false` is a measured finding. Nullable.
`freeTrialDuration`	`string \| null`	Free trial duration, or null if not offered or not measured. Nullable.
`hasEnterprisePricing`	`boolean \| null`	Whether you offer enterprise/custom pricing, or null if your own pricing wasn’t measured this run. `false` is a measured finding. Nullable.
`tierCount`	`number \| null`	Number of pricing tiers, or null if your own pricing wasn’t measured this run. Never read a null as 0 — ‘0 tiers’ is a claim about your pricing page, not about whether we reached it. Nullable.
`pricingAnalysisAvailable`	`object`	Availability flag for your own pricing. Present ONLY when your own pricing couldn’t be analyzed this run (fetch failed, or no pricing URL configured) — see `reason`. When present, every pricing metric in this object is `null`, and so are `pricePositionPercent` and all three gap flags (`hasPriceGap`, `hasFreeTierGap`, `hasEnterpriseGap`). Nothing here is a measured fact: report no price, market position, tier status, tier count or gap verdict. Only `domain` remains populated — and where no domain was on file it holds the literal placeholder `unknown` rather than being omitted, so treat that exact string as ‘no domain’, not as a site name. Note this flag is a sufficient reason for those nulls, never a necessary one: `hasPriceGap` and the market figures also null on a market too thin or too mixed to compare, with this flag absent. Absent on healthy runs (the normal path). See `items[].summary.customer.pricingAnalysisAvailable`.

items[].summary.topPriceCompetitor — object

Field	Type	Description
`domain`	`string`	Competitor domain
`price`	`number`	Price (numeric)
`planName`	`string`	Plan name

items[].summary.lowestPriceCompetitor — object

Field	Type	Description
`domain`	`string`	Competitor domain
`price`	`number`	Price (numeric)
`planName`	`string`	Plan name

items[].summary.customer.pricingAnalysisAvailable — object

Field	Type	Description
`available`	`boolean`	Always false for this discriminator.
`reason`	`string`	Why your own pricing couldn’t be analyzed. ‘pricing_fetch_failed’ = we couldn’t retrieve your pricing page this run; ‘pricing_url_not_configured’ = no pricing URL is set for your own domain. Values: `pricing_fetch_failed`, `pricing_url_not_configured`.

Paginated — pass page and limit query parameters and follow pagination.hasMore to page through the full set.

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}

Get pricing data for a specific run

GET/v1/projects/{projectId}/pricing/history/{runId}

Get full pricing intelligence data for a specific historical monitoring run, including per-competitor pricing plans, billing options, free tiers, and enterprise pricing. Competitors the run could not measure appear with a pricingDataAvailable reason instead of being omitted. Fields we could not measure are null; never read a null as zero, false or absent, and note that a measured 0 / false is reported as itself and is a real finding. A run that finished but produced no summary answers 404 run_not_summarized, which is a different fact from run_not_found: the run exists, it just has nothing to report. It used to answer 200 with an all-zero summary invented from the missing one.

Returns · { item }

Path parameters

Name	Type	Description
`runId`	`string`	Run ID
`projectId`	`string`	Project ID

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/pricing/history/507f1f77bcf86cd799439012" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "item": {
    "runId": "507f1f77bcf86cd799439011",
    "completedAt": "2026-03-15T10:00:00.000Z",
    "summary": {
      "competitorsChecked": 6,
      "competitorsSuccessful": 5,
      "customer": {
        "domain": "yoursite.com",
        "popularPlanPrice": 49,
        "popularPlanCurrency": "USD",
        "popularPlanUnit": "flat",
        "popularPlanName": "Professional",
        "pricingModel": "per-seat",
        "hasFreePlan": false,
        "hasFreeTrial": true,
        "freeTrialDuration": "14 days",
        "hasEnterprisePricing": true,
        "tierCount": 3,
        "pricingAnalysisAvailable": {
          "available": false,
          "reason": "pricing_fetch_failed"
        }
      },
      "marketAvgPrice": 59,
      "marketCurrency": "USD",
      "marketPricingUnit": "flat",
      "pricePositionPercent": 45,
      "topPriceCompetitor": {
        "domain": "rival.com",
        "price": 99,
        "planName": "Enterprise"
      },
      "lowestPriceCompetitor": {
        "domain": "rival.com",
        "price": 99,
        "planName": "Enterprise"
      },
      "pricingSampleSize": 4,
      "pricingIsReliable": true,
      "competitorsWithFreePlan": 2,
      "competitorsWithFreeTrial": 4,
      "competitorsWithEnterprise": 3,
      "activePromotionCount": 1,
      "hasPriceGap": true,
      "hasFreeTierGap": false,
      "hasEnterpriseGap": false,
      "hasPromotionAlert": true
    },
    "competitors": [
      {
        "domain": "competitor.com",
        "isOwn": false,
        "pricingUrl": "https://competitor.com/pricing",
        "pricingLocationType": "crawled",
        "content": {
          "pageTitle": "Acme Pricing - Plans for Every Team",
          "pageDescription": "Choose from flexible pricing plans starting at $9/month.",
          "mainHeadline": "Simple, Transparent Pricing",
          "pricingModel": "per-seat",
          "plans": [
            {
              "name": "Professional",
              "price": "$49/month",
              "summary": "Best for growing teams with advanced features"
            }
          ],
          "popularPlanName": "Professional",
          "hasFreePlan": true,
          "freePlanName": "Starter",
          "hasFreeTrial": true,
          "freeTrialDuration": "14 days",
          "billingCycleOffered": "monthly, annual",
          "annualDiscountAmount": "20%",
          "moneyBackGuarantee": "30-day money-back guarantee",
          "hasEnterpriseCustomPricing": true,
          "enterprisePlanCTA": "Contact Sales",
          "pricingPageFeatures": "Unlimited projects, Priority support, SSO",
          "hasActivePromotion": false,
          "promotionDetails": ""
        },
        "pricingDataAvailable": {
          "available": false,
          "reason": "no_page_found"
        }
      }
    ]
  }
}

Fields

item — object

Field	Type	Description
`runId`	`string`	Run ID
`completedAt`	`string`	When this run completed (ISO-8601)
`summary`	`object`	Run summary statistics. See `item.summary`.
`competitors`	`array<object>`	Per-competitor pricing data for this run. Every competitor this run attempted appears — rows the run could not measure carry `pricingDataAvailable` saying why instead of being dropped. See `item.competitors[]`.

item.summary — object

Field	Type	Description
`competitorsChecked`	`number`	Number of competitor pricing pages checked
`competitorsSuccessful`	`number`	Number of competitor pricing pages successfully analyzed
`customer`	`object`	Your pricing metrics. See `item.summary.customer`.
`marketAvgPrice`	`number \| null`	Market average price (numeric, in `marketCurrency`, per `marketPricingUnit`). Only comparable competitor prices are averaged: fixed monthly recurring amounts sharing BOTH that currency and that licensed unit — your own price is never included. Usage-based prices (per-GB, per-request, hourly), one-time prices, prices in other currencies, and prices in a different licensed unit are never averaged; no currency conversion and no unit mixing is ever performed, so a per-seat price and a flat monthly price never land in the same average. Null when fewer than 3 comparable competitor prices exist — treat null as ‘not enough comparable market data’, never as zero. Always quote it with its unit: ‘$59 per seat per month’ and ‘$59 per month’ are different claims. Data recorded before unit grouping existed carries no `marketPricingUnit` and its average may mix units — check for that field’s absence before quoting a historical figure. Nullable.
`marketCurrency`	`string \| null`	The currency all market figures are computed in — the majority currency among comparable competitor prices (a tie prefers your own). Together with `marketPricingUnit` it sets `marketAvgPrice`, `pricePositionPercent`, `topPriceCompetitor`, `lowestPriceCompetitor`, and which prices count toward `pricingSampleSize`. Prices in other currencies stay visible on their rows but are excluded. Null when no comparable competitor price exists, or on data recorded before currency capture existed. Nullable.
`marketPricingUnit`	`string \| null`	The licensed unit all market figures are computed in — ‘flat’ for plain monthly amounts, or ‘per-seat’ / ‘per-license’ / similar for per-unit monthly licensing. It is the majority unit among the comparable competitor prices already sharing `marketCurrency` (a tie prefers your own), and it is the second half of what makes a market figure comparable: competitors pricing in a different unit stay visible on their rows but are excluded from every market figure, because averaging ‘$15 per seat per month’ with ‘$475 per month’ describes no market that exists. Null when no comparable competitor price exists. ABSENT on data recorded before unit grouping existed — on that data the market figures were averaged across mixed units, so the absence of this field is your signal not to quote them as a like-for-like market price. Nullable.
`pricePositionPercent`	`number \| null`	Your price position vs market average (percent; negative = below market). Null when `marketAvgPrice` is null, and ALSO null whenever your own price isn’t comparable to the market — a different currency (no conversion is ever performed), a different licensed unit (compare `popularPlanUnit` with `marketPricingUnit`), or non-monthly pricing. Treat null as ‘no comparable position’, never as 0%. Nullable.
`topPriceCompetitor`	`object \| null`	Competitor with the highest comparable price (fixed monthly, in `marketCurrency`, per `marketPricingUnit`). Descriptive, not a market verdict: present at any sample size — caption it with `pricingSampleSize`. Null when no comparable competitor price exists. A competitor priced in another currency or another unit may well charge more and still not appear here. Data recorded before this change stored null whenever `pricingIsReliable` was false. Nullable. See `item.summary.topPriceCompetitor`.
`lowestPriceCompetitor`	`object \| null`	Competitor with the lowest comparable price (fixed monthly, in `marketCurrency`, per `marketPricingUnit`). Same semantics as `topPriceCompetitor` — descriptive at any sample size, null when no comparable competitor price exists. Nullable. See `item.summary.lowestPriceCompetitor`.
`pricingSampleSize`	`number`	Number of competitor prices comparable enough to aggregate: fixed monthly recurring amounts sharing both `marketCurrency` and `marketPricingUnit`, your own domain always excluded. This is the honest denominator behind `marketAvgPrice`. Competitors with usage-based, one-time, other-currency, or other-unit pricing don’t count here — their pricing model is still visible on their rows, and a low number here usually means the market prices in several different ways rather than that we failed to read it. On data recorded before this change, this counted any numeric price regardless of unit or currency.
`pricingIsReliable`	`boolean`	True when `pricingSampleSize` >= 3 — enough comparable competitor prices for market-average and position claims. When false, `marketAvgPrice`, `pricePositionPercent` and `hasPriceGap` are all null: there is no market average to sit above, so there is no verdict either. `topPriceCompetitor` / `lowestPriceCompetitor` remain as descriptive data points.
`competitorsWithFreePlan`	`number`	Number of competitors offering a free plan
`competitorsWithFreeTrial`	`number`	Number of competitors offering a free trial
`competitorsWithEnterprise`	`number`	Number of competitors with enterprise pricing
`activePromotionCount`	`number`	Number of competitors running active promotions
`hasPriceGap`	`boolean \| null`	Whether you sit 20%+ above the market average. `false` means measured, with no gap. Null in three cases, all of them ‘we couldn’t make the comparison’: your own pricing wasn’t measured this run; `pricingIsReliable` is false (too few comparable competitor prices to establish a market average); or `pricePositionPercent` is null because your own price isn’t comparable to the market — a different currency, a different licensed unit, or usage-based rather than a fixed monthly amount. That is a WIDER set of null conditions than the other two gap flags carry, so check this field’s own list rather than assuming all three null together. Never read a null as ‘no gap’. Nullable.
`hasFreeTierGap`	`boolean \| null`	Whether at least half of your tracked competitors offer a free tier and you don’t. `false` means measured, with no gap. Null when either side of the comparison is missing — those are its only two null conditions: your own pricing wasn’t measured this run, or no competitor was measured at all (with no market there is no majority to be behind). It does NOT null on a thin comparable-price sample, because free-tier availability doesn’t depend on prices being comparable: a `false` here alongside a null `hasPriceGap` is consistent, not contradictory. Read `competitorsWithFreePlan` alongside it. Nullable.
`hasEnterpriseGap`	`boolean \| null`	Whether competitors offer enterprise pricing and you don’t. Null when either side of the comparison is missing — your own pricing unmeasured, or no competitor measured. Those are its only two null conditions; like `hasFreeTierGap`, and unlike `hasPriceGap`, it does not null on a thin comparable-price sample. `false` means measured, with no gap. Nullable.
`hasPromotionAlert`	`boolean`	Whether competitors are running promotions you should know about

item.competitors[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`isOwn`	`boolean`	Whether this is the project’s own domain
`pricingUrl`	`string \| null`	Pricing page URL that was analyzed, or null exactly when `pricingDataAvailable` is present (no pricing data on this row). Nullable.
`pricingLocationType`	`string \| null`	How the pricing page was located, or null exactly when `pricingDataAvailable` is present. Nullable.
`content`	`object \| null`	Extracted pricing page content, or null exactly when `pricingDataAvailable` is present. A null here means this competitor’s pricing is unmeasured — never ‘they offer no pricing’. Nullable. See `item.competitors[].content`.
`pricingDataAvailable`	`object`	Present ONLY when this row has no pricing data — `reason` says why. When present, `pricingUrl`, `pricingLocationType`, and `content` are null: branch on this field before quoting any price, plan, or pricing fact from the row. Absent on measured rows, including every response from before this field existed. On the dashboard, competitor rows keep their most recent successful read, so this marker appears only for a competitor never read successfully — its `reason` reflects the latest completed check. Your own row is different: it always reflects the latest completed check, success or failure. In run-detail responses the marker is scoped to that run. See `item.competitors[].pricingDataAvailable`.

item.summary.customer — object

Field	Type	Description
`domain`	`string`	Your domain. Unlike every other field here it is not nulled when nothing was measured, because it stays a known fact — it is read from your project’s own configuration, not from the pricing check. The one exception is a project with no own-domain entry on file at all, where there is no domain to report and this carries the literal placeholder `unknown`. That string is a marker, never a domain: don’t render it, resolve it, or describe it as a site.
`popularPlanPrice`	`number \| null`	The price of the plan named by `popularPlanName` — which is not always the plan you badge as most popular; see that field. Null if unavailable. Check `popularPlanCurrency` before rendering a currency symbol next to it — this amount is in whatever currency your pricing page uses, not necessarily USD — and `popularPlanUnit` before describing it, since it may be priced per seat rather than flat. Nullable.
`popularPlanCurrency`	`string \| null`	Currency of `popularPlanPrice` as read off your pricing page — ‘USD’ / ‘EUR’ / ‘GBP’, or the verbatim currency symbol for other currencies. Null when no currency could be detected on the page, or on data recorded before currency capture existed — never treat null as USD. Nullable.
`popularPlanUnit`	`string \| null`	The licensed unit your popular plan price is quoted in — ‘flat’ for a plain monthly amount, or ‘per-seat’ / ‘per-license’ / similar for per-unit monthly licensing. Null when your price isn’t a comparable monthly amount at all (usage-based, one-time, or unreadable), and absent on data recorded before unit capture existed — never treat either as ‘flat’. Compare it with `marketPricingUnit`: when the two differ, `pricePositionPercent` is null because a per-seat price and a flat price are not the same kind of number, however similar the figures look. Nullable.
`popularPlanName`	`string \| null`	The plan we use to represent your pricing: your own ‘most popular’ badge when that plan lists a comparable monthly price, otherwise the cheapest plan on your page that does — a free or quote-only flagship carries no amount to position against a market. So this is not always the plan you feature. `popularPlanPrice`, `popularPlanCurrency` and `popularPlanUnit` all describe THIS plan, whichever one it is. Null if your pricing wasn’t measured this run. Nullable.
`pricingModel`	`string \| null`	Your pricing model type, or null if unavailable. Nullable.
`hasFreePlan`	`boolean \| null`	Whether you offer a permanent free plan, or null if your own pricing wasn’t measured this run. `false` is a measured finding — we read your pricing page and there is no free plan. Never report a null as ‘no free plan’. Nullable.
`hasFreeTrial`	`boolean \| null`	Whether you offer a free trial, or null if your own pricing wasn’t measured this run. `false` is a measured finding. Nullable.
`freeTrialDuration`	`string \| null`	Free trial duration, or null if not offered or not measured. Nullable.
`hasEnterprisePricing`	`boolean \| null`	Whether you offer enterprise/custom pricing, or null if your own pricing wasn’t measured this run. `false` is a measured finding. Nullable.
`tierCount`	`number \| null`	Number of pricing tiers, or null if your own pricing wasn’t measured this run. Never read a null as 0 — ‘0 tiers’ is a claim about your pricing page, not about whether we reached it. Nullable.
`pricingAnalysisAvailable`	`object`	Availability flag for your own pricing. Present ONLY when your own pricing couldn’t be analyzed this run (fetch failed, or no pricing URL configured) — see `reason`. When present, every pricing metric in this object is `null`, and so are `pricePositionPercent` and all three gap flags (`hasPriceGap`, `hasFreeTierGap`, `hasEnterpriseGap`). Nothing here is a measured fact: report no price, market position, tier status, tier count or gap verdict. Only `domain` remains populated — and where no domain was on file it holds the literal placeholder `unknown` rather than being omitted, so treat that exact string as ‘no domain’, not as a site name. Note this flag is a sufficient reason for those nulls, never a necessary one: `hasPriceGap` and the market figures also null on a market too thin or too mixed to compare, with this flag absent. Absent on healthy runs (the normal path). See `item.summary.customer.pricingAnalysisAvailable`.

item.summary.topPriceCompetitor — object

Field	Type	Description
`domain`	`string`	Competitor domain
`price`	`number`	Price (numeric)
`planName`	`string`	Plan name

item.summary.lowestPriceCompetitor — object

Field	Type	Description
`domain`	`string`	Competitor domain
`price`	`number`	Price (numeric)
`planName`	`string`	Plan name

item.competitors[].content — object

Field	Type	Description
`pageTitle`	`string`	Page title
`pageDescription`	`string`	Page meta description
`mainHeadline`	`string`	Main pricing page headline
`pricingModel`	`string`	Pricing model type
`plans`	`array<object>`	Structured pricing plans extracted from the page. See `item.competitors[].content.plans[]`.
`popularPlanName`	`string`	Name of the recommended/popular plan
`hasFreePlan`	`boolean`	Whether a free plan is offered
`freePlanName`	`string`	Name of the free plan if offered
`hasFreeTrial`	`boolean`	Whether a free trial is offered
`freeTrialDuration`	`string`	Free trial duration if offered
`billingCycleOffered`	`string`	Billing cycles offered
`annualDiscountAmount`	`string`	Annual discount amount if offered
`moneyBackGuarantee`	`string`	Money-back guarantee details
`hasEnterpriseCustomPricing`	`boolean`	Whether enterprise/custom pricing is available
`enterprisePlanCTA`	`string`	Enterprise plan CTA text
`pricingPageFeatures`	`string`	Key features listed on pricing page (comma-separated)
`hasActivePromotion`	`boolean`	Whether an active promotion is running
`promotionDetails`	`string`	Promotion details if active

item.competitors[].pricingDataAvailable — object

Field	Type	Description
`available`	`boolean`	Always false — present only when this row carries no pricing data
`reason`	`string`	Why this row has no pricing data. ‘no_page_found’ = we didn’t find a pricing page for this competitor — they may simply not publish one; if you know the URL, adding it in competitor settings enables this check. ‘fetch_failed_their_side’ = their pricing page didn’t respond to this check (blocked, errored, or timed out) — nothing was measured. ‘fetch_failed_our_side’ = a temporary problem on our side stopped this check — nothing was measured, and it says nothing about the competitor. Never turn any of these reasons into a pricing claim: a row carrying one has no price, plan, or tier facts to quote. Values: `no_page_found`, `fetch_failed_their_side`, `fetch_failed_our_side`.

item.summary.customer.pricingAnalysisAvailable — object

Field	Type	Description
`available`	`boolean`	Always false for this discriminator.
`reason`	`string`	Why your own pricing couldn’t be analyzed. ‘pricing_fetch_failed’ = we couldn’t retrieve your pricing page this run; ‘pricing_url_not_configured’ = no pricing URL is set for your own domain. Values: `pricing_fetch_failed`, `pricing_url_not_configured`.

item.competitors[].content.plans[] — each entry

Field	Type	Description
`name`	`string`	Plan name
`price`	`string`	Plan price
`summary`	`string`	Brief summary of the plan

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
404	`run_not_found` · `run_not_summarized`	No `run` matches the id in the path.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}