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.

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,
        "popularPlanName": "Professional",
        "pricingModel": "per-seat",
        "hasFreePlan": false,
        "hasFreeTrial": true,
        "freeTrialDuration": "14 days",
        "hasEnterprisePricing": true,
        "tierCount": 3
      },
      "marketAvgPrice": 59,
      "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": ""
        }
      }
    ]
  }
}

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. 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). Null when the competitor sample is too small to compute a meaningful market average. Nullable.
`pricePositionPercent`	`number \| null`	Your price position vs market average (percent; negative = below market). Null when the competitor sample is too small for a meaningful comparison. Nullable.
`topPriceCompetitor`	`object \| null`	Competitor with the highest price. Null when the competitor sample is too small for a meaningful comparison. Nullable. See `item.summary.topPriceCompetitor`.
`lowestPriceCompetitor`	`object \| null`	Competitor with the lowest price. Null when the competitor sample is too small for a meaningful comparison. Nullable. See `item.summary.lowestPriceCompetitor`.
`pricingSampleSize`	`number`	Count of competitors with parseable popular-plan pricing in this run (used to gate market-comparison fields).
`pricingIsReliable`	`boolean`	True when the competitor pricing sample is large enough to support market-comparison framings.
`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`	Whether a significant price gap exists vs market
`hasFreeTierGap`	`boolean`	Whether competitors offer free tier but you don’t
`hasEnterpriseGap`	`boolean`	Whether competitors offer enterprise pricing but you don’t
`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`	Pricing page URL that was analyzed
`pricingLocationType`	`string`	How the pricing page was located
`content`	`object`	Extracted pricing page content. See `item.competitors[].content`.

item.summary.customer — object

Field	Type	Description
`domain`	`string`	Your domain
`popularPlanPrice`	`number \| null`	Your popular plan price (numeric), or null if unavailable. Nullable.
`popularPlanName`	`string \| null`	Your popular plan name, or null if unavailable. Nullable.
`pricingModel`	`string \| null`	Your pricing model type, or null if unavailable. Nullable.
`hasFreePlan`	`boolean`	Whether you offer a free plan
`hasFreeTrial`	`boolean`	Whether you offer a free trial
`freeTrialDuration`	`string \| null`	Free trial duration, or null if not offered. Nullable.
`hasEnterprisePricing`	`boolean`	Whether you offer enterprise/custom pricing
`tierCount`	`number`	Number of pricing tiers

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[].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 `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.

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,
          "popularPlanName": "Professional",
          "pricingModel": "per-seat",
          "hasFreePlan": false,
          "hasFreeTrial": true,
          "freeTrialDuration": "14 days",
          "hasEnterprisePricing": true,
          "tierCount": 3
        },
        "marketAvgPrice": 59,
        "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). Null when the competitor sample is too small to compute a meaningful market average. Nullable.
`pricePositionPercent`	`number \| null`	Your price position vs market average (percent; negative = below market). Null when the competitor sample is too small for a meaningful comparison. Nullable.
`topPriceCompetitor`	`object \| null`	Competitor with the highest price. Null when the competitor sample is too small for a meaningful comparison. Nullable. See `items[].summary.topPriceCompetitor`.
`lowestPriceCompetitor`	`object \| null`	Competitor with the lowest price. Null when the competitor sample is too small for a meaningful comparison. Nullable. See `items[].summary.lowestPriceCompetitor`.
`pricingSampleSize`	`number`	Count of competitors with parseable popular-plan pricing in this run (used to gate market-comparison fields).
`pricingIsReliable`	`boolean`	True when the competitor pricing sample is large enough to support market-comparison framings.
`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`	Whether a significant price gap exists vs market
`hasFreeTierGap`	`boolean`	Whether competitors offer free tier but you don’t
`hasEnterpriseGap`	`boolean`	Whether competitors offer enterprise pricing but you don’t
`hasPromotionAlert`	`boolean`	Whether competitors are running promotions you should know about

items[].summary.customer — object

Field	Type	Description
`domain`	`string`	Your domain
`popularPlanPrice`	`number \| null`	Your popular plan price (numeric), or null if unavailable. Nullable.
`popularPlanName`	`string \| null`	Your popular plan name, or null if unavailable. Nullable.
`pricingModel`	`string \| null`	Your pricing model type, or null if unavailable. Nullable.
`hasFreePlan`	`boolean`	Whether you offer a free plan
`hasFreeTrial`	`boolean`	Whether you offer a free trial
`freeTrialDuration`	`string \| null`	Free trial duration, or null if not offered. Nullable.
`hasEnterprisePricing`	`boolean`	Whether you offer enterprise/custom pricing
`tierCount`	`number`	Number of pricing tiers

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

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.

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,
        "popularPlanName": "Professional",
        "pricingModel": "per-seat",
        "hasFreePlan": false,
        "hasFreeTrial": true,
        "freeTrialDuration": "14 days",
        "hasEnterprisePricing": true,
        "tierCount": 3
      },
      "marketAvgPrice": 59,
      "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": ""
        }
      }
    ]
  }
}

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. 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). Null when the competitor sample is too small to compute a meaningful market average. Nullable.
`pricePositionPercent`	`number \| null`	Your price position vs market average (percent; negative = below market). Null when the competitor sample is too small for a meaningful comparison. Nullable.
`topPriceCompetitor`	`object \| null`	Competitor with the highest price. Null when the competitor sample is too small for a meaningful comparison. Nullable. See `item.summary.topPriceCompetitor`.
`lowestPriceCompetitor`	`object \| null`	Competitor with the lowest price. Null when the competitor sample is too small for a meaningful comparison. Nullable. See `item.summary.lowestPriceCompetitor`.
`pricingSampleSize`	`number`	Count of competitors with parseable popular-plan pricing in this run (used to gate market-comparison fields).
`pricingIsReliable`	`boolean`	True when the competitor pricing sample is large enough to support market-comparison framings.
`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`	Whether a significant price gap exists vs market
`hasFreeTierGap`	`boolean`	Whether competitors offer free tier but you don’t
`hasEnterpriseGap`	`boolean`	Whether competitors offer enterprise pricing but you don’t
`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`	Pricing page URL that was analyzed
`pricingLocationType`	`string`	How the pricing page was located
`content`	`object`	Extracted pricing page content. See `item.competitors[].content`.

item.summary.customer — object

Field	Type	Description
`domain`	`string`	Your domain
`popularPlanPrice`	`number \| null`	Your popular plan price (numeric), or null if unavailable. Nullable.
`popularPlanName`	`string \| null`	Your popular plan name, or null if unavailable. Nullable.
`pricingModel`	`string \| null`	Your pricing model type, or null if unavailable. Nullable.
`hasFreePlan`	`boolean`	Whether you offer a free plan
`hasFreeTrial`	`boolean`	Whether you offer a free trial
`freeTrialDuration`	`string \| null`	Free trial duration, or null if not offered. Nullable.
`hasEnterprisePricing`	`boolean`	Whether you offer enterprise/custom pricing
`tierCount`	`number`	Number of pricing tiers

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[].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`	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
  }
}