Positioning

REST endpoints for Positioning. 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 positioning data

GET/v1/projects/{projectId}/positioning

Get the latest positioning data for all competitors in a project. Returns homepage messaging, value propositions, CTAs, target audience, and competitive messaging 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. For the messaging strings the distinction is sharp: a measured EMPTY STRING means we read the page and there is genuinely no call to action, which is a finding; a null means we never read 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/positioning" \
  -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",
        "messagingStrengthScore": 72,
        "hasSpecificHeadline": true,
        "hasStrongCta": true,
        "showsPricing": false,
        "hasFreeTrial": true,
        "primaryCta": "Start Free Trial",
        "mainHeadline": "Ship Projects 10x Faster",
        "messagingAnalysisAvailable": {
          "available": false,
          "reason": "homepage_fetch_failed"
        }
      },
      "topMessagingCompetitor": {
        "domain": "rival.com",
        "messagingStrengthScore": 88,
        "primaryCta": "Try It Free",
        "mainHeadline": "The Future of Work"
      },
      "ctaComparison": {
        "yourCta": "Start Free Trial",
        "strongestCompetitorCta": "Get Started — It's Free",
        "strongestCompetitorDomain": "rival.com"
      },
      "pricingComparison": {
        "competitorsShowingPrice": 3,
        "competitorsWithFreeTrial": 4,
        "youShowPrice": false,
        "youHaveFreeTrial": true
      },
      "messagingScoreGap": -16
    },
    "competitors": [
      {
        "domain": "competitor.com",
        "isOwn": false,
        "homepageUrl": "https://competitor.com",
        "content": {
          "pageTitle": "Acme - The #1 Project Management Tool",
          "pageDescription": "Manage projects, track tasks, and collaborate with your team.",
          "mainHeadline": "Ship Projects 10x Faster",
          "tagline": "The all-in-one platform for modern teams",
          "valueProposition": "Streamline your workflow with AI-powered project management",
          "primaryCTA": "Start Free Trial",
          "secondaryCTA": "Book a Demo",
          "keyOfferings": [
            "Task Management",
            "Time Tracking",
            "Team Collaboration"
          ],
          "targetAudience": "Product teams and agencies",
          "mainDifferentiator": "AI-powered automation that saves 5 hours per week",
          "pricingMentioned": true,
          "startingPrice": "$9/month",
          "hasFreeTrial": true,
          "freeTrialDuration": "14 days"
        }
      }
    ]
  }
}

Fields

item — object

Field	Type	Description
`lastUpdatedAt`	`string`	When this data was last updated (ISO-8601)
`summary`	`object`	Run summary with messaging gap analysis. See `item.summary`.
`competitors`	`array<object>`	Per-competitor positioning data. See `item.competitors[]`.

item.summary — object

Field	Type	Description
`competitorsChecked`	`number`	Number of competitor homepages checked in this run
`competitorsSuccessful`	`number`	Number of competitor homepages successfully analyzed
`customer`	`object`	Your domain’s messaging metrics. See `item.summary.customer`.
`topMessagingCompetitor`	`object \| null`	Competitor with the highest messaging strength score, or null if no competitors checked. Nullable. See `item.summary.topMessagingCompetitor`.
`ctaComparison`	`object \| null`	CTA comparison between you and the strongest competitor, or null if unavailable. Nullable. See `item.summary.ctaComparison`.
`pricingComparison`	`object`	Pricing transparency comparison across competitors. See `item.summary.pricingComparison`.
`messagingScoreGap`	`number \| null`	Your messaging score minus the top competitor’s (negative = you are behind), or null when there is no comparison to make: your own homepage was unmeasured, or no competitor was scored. A 0 means genuinely level. Was a forced 0, which read as ‘level’ either way. Nullable.

item.competitors[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`isOwn`	`boolean`	Whether this is the project’s own domain
`homepageUrl`	`string`	Homepage URL that was analyzed
`content`	`object`	Extracted homepage content and messaging. See `item.competitors[].content`.

item.summary.customer — object

Field	Type	Description
`domain`	`string`	Your domain
`messagingStrengthScore`	`number \| null`	Messaging strength score (0-100) based on homepage completeness. `null` when your own homepage couldn’t be analyzed this run (see `messagingAnalysisAvailable`) — do not report a messaging score or you-vs-competitor ranking in that case. Nullable.
`hasSpecificHeadline`	`boolean \| null`	Whether your headline includes specific metrics or numbers, or null when your own homepage couldn’t be analyzed this run. A measured `false` is REAL — we read the page and the headline is generic — so never report a null as a generic headline. Nullable.
`hasStrongCta`	`boolean \| null`	Whether your CTA is strong and specific (not just ‘Get Started’), or null when your homepage was unmeasured. A measured `false` is a real finding. Nullable.
`showsPricing`	`boolean \| null`	Whether pricing is shown on your homepage, or null when it was unmeasured. A measured `false` is a real finding. Nullable.
`hasFreeTrial`	`boolean \| null`	Whether you offer a free trial, or null when your homepage was unmeasured. A measured `false` is a real finding. Nullable.
`primaryCta`	`string \| null`	Your primary CTA text, or null when your homepage was unmeasured. Note the distinction: a measured empty string means we read the page and there IS no call to action — a real finding — while null means we never read it. Nullable.
`mainHeadline`	`string \| null`	Your main headline, or null when your homepage was unmeasured. A measured empty string is a real finding. Nullable.
`messagingAnalysisAvailable`	`object`	Availability flag for your own homepage messaging. Present ONLY when your own homepage couldn’t be analyzed this run (fetch failed, or no homepage URL configured) — see `reason`. When present, EVERY metric in this object is null, `messagingScoreGap` is null, and your own cells in the comparison widgets (`ctaComparison.yourCta`, `pricingComparison.youShowPrice`, `pricingComparison.youHaveFreeTrial`) are null too. Nothing here is a measured fact; the nulls say so on their own, and this field records why. Only `domain` remains populated. Absent on healthy runs (the normal path). See `item.summary.customer.messagingAnalysisAvailable`.

item.summary.topMessagingCompetitor — object

Field	Type	Description
`domain`	`string`	Top messaging competitor domain
`messagingStrengthScore`	`number`	Their messaging strength score (0-100)
`primaryCta`	`string`	Their primary CTA text
`mainHeadline`	`string`	Their main headline

item.summary.ctaComparison — object

Field	Type	Description
`yourCta`	`string \| null`	Your primary CTA text, or null when your own homepage couldn’t be analyzed this run (see `customer.messagingAnalysisAvailable`) — never report a ‘no primary CTA’ finding or a your-CTA-vs-competitor comparison off a null. A measured homepage with no CTA is an empty string, not null. Nullable.
`strongestCompetitorCta`	`string`	Strongest competitor’s CTA text
`strongestCompetitorDomain`	`string`	Domain of the competitor with the strongest CTA

item.summary.pricingComparison — object

Field	Type	Description
`competitorsShowingPrice`	`number`	Number of competitors showing pricing on homepage
`competitorsWithFreeTrial`	`number`	Number of competitors offering a free trial
`youShowPrice`	`boolean \| null`	Whether you show pricing on your homepage, or null when your own homepage couldn’t be analyzed this run (see `customer.messagingAnalysisAvailable`) — never report a pricing-transparency posture off a null. A measured homepage that genuinely shows no pricing is false, not null. Nullable.
`youHaveFreeTrial`	`boolean \| null`	Whether you offer a free trial, or null when your own homepage couldn’t be analyzed this run (see `customer.messagingAnalysisAvailable`) — never report a free-trial claim off a null. A measured homepage with genuinely no free trial is false, not null. Nullable.

item.competitors[].content — object

Field	Type	Description
`pageTitle`	`string`	Page title
`pageDescription`	`string`	Page meta description
`mainHeadline`	`string`	Main homepage headline
`tagline`	`string`	Tagline or subheadline
`valueProposition`	`string`	Core value proposition statement
`primaryCTA`	`string`	Primary call-to-action text
`secondaryCTA`	`string`	Secondary call-to-action text
`keyOfferings`	`array<string>`	Key product offerings listed on homepage
`targetAudience`	`string`	Target audience as described on homepage
`mainDifferentiator`	`string`	Main differentiator or unique selling point
`pricingMentioned`	`boolean`	Whether pricing is mentioned on the homepage
`startingPrice`	`string`	Starting price if mentioned on homepage
`hasFreeTrial`	`boolean`	Whether a free trial is offered
`freeTrialDuration`	`string`	Free trial duration if offered

item.summary.customer.messagingAnalysisAvailable — object

Field	Type	Description
`available`	`boolean`	Always false for this discriminator.
`reason`	`string`	Why your homepage messaging couldn’t be scored. ‘homepage_fetch_failed’ = we couldn’t retrieve your homepage this run; ‘homepage_url_not_configured’ = no homepage URL is set for your own domain. Values: `homepage_fetch_failed`, `homepage_url_not_configured`.

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 positioning run history

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

Get paginated history of positioning monitoring runs for a project. Each entry includes run timing and summary statistics with messaging 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/positioning/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",
          "messagingStrengthScore": 72,
          "hasSpecificHeadline": true,
          "hasStrongCta": true,
          "showsPricing": false,
          "hasFreeTrial": true,
          "primaryCta": "Start Free Trial",
          "mainHeadline": "Ship Projects 10x Faster",
          "messagingAnalysisAvailable": {
            "available": false,
            "reason": "homepage_fetch_failed"
          }
        },
        "topMessagingCompetitor": {
          "domain": "rival.com",
          "messagingStrengthScore": 88,
          "primaryCta": "Try It Free",
          "mainHeadline": "The Future of Work"
        },
        "ctaComparison": {
          "yourCta": "Start Free Trial",
          "strongestCompetitorCta": "Get Started — It's Free",
          "strongestCompetitorDomain": "rival.com"
        },
        "pricingComparison": {
          "competitorsShowingPrice": 3,
          "competitorsWithFreeTrial": 4,
          "youShowPrice": false,
          "youHaveFreeTrial": true
        },
        "messagingScoreGap": -16
      }
    }
  ],
  "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 homepages checked in this run
`competitorsSuccessful`	`number`	Number of competitor homepages successfully analyzed
`customer`	`object`	Your domain’s messaging metrics. See `items[].summary.customer`.
`topMessagingCompetitor`	`object \| null`	Competitor with the highest messaging strength score, or null if no competitors checked. Nullable. See `items[].summary.topMessagingCompetitor`.
`ctaComparison`	`object \| null`	CTA comparison between you and the strongest competitor, or null if unavailable. Nullable. See `items[].summary.ctaComparison`.
`pricingComparison`	`object`	Pricing transparency comparison across competitors. See `items[].summary.pricingComparison`.
`messagingScoreGap`	`number \| null`	Your messaging score minus the top competitor’s (negative = you are behind), or null when there is no comparison to make: your own homepage was unmeasured, or no competitor was scored. A 0 means genuinely level. Was a forced 0, which read as ‘level’ either way. Nullable.

items[].summary.customer — object

Field	Type	Description
`domain`	`string`	Your domain
`messagingStrengthScore`	`number \| null`	Messaging strength score (0-100) based on homepage completeness. `null` when your own homepage couldn’t be analyzed this run (see `messagingAnalysisAvailable`) — do not report a messaging score or you-vs-competitor ranking in that case. Nullable.
`hasSpecificHeadline`	`boolean \| null`	Whether your headline includes specific metrics or numbers, or null when your own homepage couldn’t be analyzed this run. A measured `false` is REAL — we read the page and the headline is generic — so never report a null as a generic headline. Nullable.
`hasStrongCta`	`boolean \| null`	Whether your CTA is strong and specific (not just ‘Get Started’), or null when your homepage was unmeasured. A measured `false` is a real finding. Nullable.
`showsPricing`	`boolean \| null`	Whether pricing is shown on your homepage, or null when it was unmeasured. A measured `false` is a real finding. Nullable.
`hasFreeTrial`	`boolean \| null`	Whether you offer a free trial, or null when your homepage was unmeasured. A measured `false` is a real finding. Nullable.
`primaryCta`	`string \| null`	Your primary CTA text, or null when your homepage was unmeasured. Note the distinction: a measured empty string means we read the page and there IS no call to action — a real finding — while null means we never read it. Nullable.
`mainHeadline`	`string \| null`	Your main headline, or null when your homepage was unmeasured. A measured empty string is a real finding. Nullable.
`messagingAnalysisAvailable`	`object`	Availability flag for your own homepage messaging. Present ONLY when your own homepage couldn’t be analyzed this run (fetch failed, or no homepage URL configured) — see `reason`. When present, EVERY metric in this object is null, `messagingScoreGap` is null, and your own cells in the comparison widgets (`ctaComparison.yourCta`, `pricingComparison.youShowPrice`, `pricingComparison.youHaveFreeTrial`) are null too. Nothing here is a measured fact; the nulls say so on their own, and this field records why. Only `domain` remains populated. Absent on healthy runs (the normal path). See `items[].summary.customer.messagingAnalysisAvailable`.

items[].summary.topMessagingCompetitor — object

Field	Type	Description
`domain`	`string`	Top messaging competitor domain
`messagingStrengthScore`	`number`	Their messaging strength score (0-100)
`primaryCta`	`string`	Their primary CTA text
`mainHeadline`	`string`	Their main headline

items[].summary.ctaComparison — object

Field	Type	Description
`yourCta`	`string \| null`	Your primary CTA text, or null when your own homepage couldn’t be analyzed this run (see `customer.messagingAnalysisAvailable`) — never report a ‘no primary CTA’ finding or a your-CTA-vs-competitor comparison off a null. A measured homepage with no CTA is an empty string, not null. Nullable.
`strongestCompetitorCta`	`string`	Strongest competitor’s CTA text
`strongestCompetitorDomain`	`string`	Domain of the competitor with the strongest CTA

items[].summary.pricingComparison — object

Field	Type	Description
`competitorsShowingPrice`	`number`	Number of competitors showing pricing on homepage
`competitorsWithFreeTrial`	`number`	Number of competitors offering a free trial
`youShowPrice`	`boolean \| null`	Whether you show pricing on your homepage, or null when your own homepage couldn’t be analyzed this run (see `customer.messagingAnalysisAvailable`) — never report a pricing-transparency posture off a null. A measured homepage that genuinely shows no pricing is false, not null. Nullable.
`youHaveFreeTrial`	`boolean \| null`	Whether you offer a free trial, or null when your own homepage couldn’t be analyzed this run (see `customer.messagingAnalysisAvailable`) — never report a free-trial claim off a null. A measured homepage with genuinely no free trial is false, not null. Nullable.

items[].summary.customer.messagingAnalysisAvailable — object

Field	Type	Description
`available`	`boolean`	Always false for this discriminator.
`reason`	`string`	Why your homepage messaging couldn’t be scored. ‘homepage_fetch_failed’ = we couldn’t retrieve your homepage this run; ‘homepage_url_not_configured’ = no homepage URL is set for your own domain. Values: `homepage_fetch_failed`, `homepage_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 positioning data for a specific run

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

Get full positioning data for a specific historical monitoring run, including per-competitor homepage messaging, value propositions, CTAs, and audience data. 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. 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/positioning/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",
        "messagingStrengthScore": 72,
        "hasSpecificHeadline": true,
        "hasStrongCta": true,
        "showsPricing": false,
        "hasFreeTrial": true,
        "primaryCta": "Start Free Trial",
        "mainHeadline": "Ship Projects 10x Faster",
        "messagingAnalysisAvailable": {
          "available": false,
          "reason": "homepage_fetch_failed"
        }
      },
      "topMessagingCompetitor": {
        "domain": "rival.com",
        "messagingStrengthScore": 88,
        "primaryCta": "Try It Free",
        "mainHeadline": "The Future of Work"
      },
      "ctaComparison": {
        "yourCta": "Start Free Trial",
        "strongestCompetitorCta": "Get Started — It's Free",
        "strongestCompetitorDomain": "rival.com"
      },
      "pricingComparison": {
        "competitorsShowingPrice": 3,
        "competitorsWithFreeTrial": 4,
        "youShowPrice": false,
        "youHaveFreeTrial": true
      },
      "messagingScoreGap": -16
    },
    "competitors": [
      {
        "domain": "competitor.com",
        "isOwn": false,
        "homepageUrl": "https://competitor.com",
        "content": {
          "pageTitle": "Acme - The #1 Project Management Tool",
          "pageDescription": "Manage projects, track tasks, and collaborate with your team.",
          "mainHeadline": "Ship Projects 10x Faster",
          "tagline": "The all-in-one platform for modern teams",
          "valueProposition": "Streamline your workflow with AI-powered project management",
          "primaryCTA": "Start Free Trial",
          "secondaryCTA": "Book a Demo",
          "keyOfferings": [
            "Task Management",
            "Time Tracking",
            "Team Collaboration"
          ],
          "targetAudience": "Product teams and agencies",
          "mainDifferentiator": "AI-powered automation that saves 5 hours per week",
          "pricingMentioned": true,
          "startingPrice": "$9/month",
          "hasFreeTrial": true,
          "freeTrialDuration": "14 days"
        }
      }
    ]
  }
}

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 positioning data for this run. See `item.competitors[]`.

item.summary — object

Field	Type	Description
`competitorsChecked`	`number`	Number of competitor homepages checked in this run
`competitorsSuccessful`	`number`	Number of competitor homepages successfully analyzed
`customer`	`object`	Your domain’s messaging metrics. See `item.summary.customer`.
`topMessagingCompetitor`	`object \| null`	Competitor with the highest messaging strength score, or null if no competitors checked. Nullable. See `item.summary.topMessagingCompetitor`.
`ctaComparison`	`object \| null`	CTA comparison between you and the strongest competitor, or null if unavailable. Nullable. See `item.summary.ctaComparison`.
`pricingComparison`	`object`	Pricing transparency comparison across competitors. See `item.summary.pricingComparison`.
`messagingScoreGap`	`number \| null`	Your messaging score minus the top competitor’s (negative = you are behind), or null when there is no comparison to make: your own homepage was unmeasured, or no competitor was scored. A 0 means genuinely level. Was a forced 0, which read as ‘level’ either way. Nullable.

item.competitors[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`isOwn`	`boolean`	Whether this is the project’s own domain
`homepageUrl`	`string`	Homepage URL that was analyzed
`content`	`object`	Extracted homepage content and messaging. See `item.competitors[].content`.

item.summary.customer — object

Field	Type	Description
`domain`	`string`	Your domain
`messagingStrengthScore`	`number \| null`	Messaging strength score (0-100) based on homepage completeness. `null` when your own homepage couldn’t be analyzed this run (see `messagingAnalysisAvailable`) — do not report a messaging score or you-vs-competitor ranking in that case. Nullable.
`hasSpecificHeadline`	`boolean \| null`	Whether your headline includes specific metrics or numbers, or null when your own homepage couldn’t be analyzed this run. A measured `false` is REAL — we read the page and the headline is generic — so never report a null as a generic headline. Nullable.
`hasStrongCta`	`boolean \| null`	Whether your CTA is strong and specific (not just ‘Get Started’), or null when your homepage was unmeasured. A measured `false` is a real finding. Nullable.
`showsPricing`	`boolean \| null`	Whether pricing is shown on your homepage, or null when it was unmeasured. A measured `false` is a real finding. Nullable.
`hasFreeTrial`	`boolean \| null`	Whether you offer a free trial, or null when your homepage was unmeasured. A measured `false` is a real finding. Nullable.
`primaryCta`	`string \| null`	Your primary CTA text, or null when your homepage was unmeasured. Note the distinction: a measured empty string means we read the page and there IS no call to action — a real finding — while null means we never read it. Nullable.
`mainHeadline`	`string \| null`	Your main headline, or null when your homepage was unmeasured. A measured empty string is a real finding. Nullable.
`messagingAnalysisAvailable`	`object`	Availability flag for your own homepage messaging. Present ONLY when your own homepage couldn’t be analyzed this run (fetch failed, or no homepage URL configured) — see `reason`. When present, EVERY metric in this object is null, `messagingScoreGap` is null, and your own cells in the comparison widgets (`ctaComparison.yourCta`, `pricingComparison.youShowPrice`, `pricingComparison.youHaveFreeTrial`) are null too. Nothing here is a measured fact; the nulls say so on their own, and this field records why. Only `domain` remains populated. Absent on healthy runs (the normal path). See `item.summary.customer.messagingAnalysisAvailable`.

item.summary.topMessagingCompetitor — object

Field	Type	Description
`domain`	`string`	Top messaging competitor domain
`messagingStrengthScore`	`number`	Their messaging strength score (0-100)
`primaryCta`	`string`	Their primary CTA text
`mainHeadline`	`string`	Their main headline

item.summary.ctaComparison — object

Field	Type	Description
`yourCta`	`string \| null`	Your primary CTA text, or null when your own homepage couldn’t be analyzed this run (see `customer.messagingAnalysisAvailable`) — never report a ‘no primary CTA’ finding or a your-CTA-vs-competitor comparison off a null. A measured homepage with no CTA is an empty string, not null. Nullable.
`strongestCompetitorCta`	`string`	Strongest competitor’s CTA text
`strongestCompetitorDomain`	`string`	Domain of the competitor with the strongest CTA

item.summary.pricingComparison — object

Field	Type	Description
`competitorsShowingPrice`	`number`	Number of competitors showing pricing on homepage
`competitorsWithFreeTrial`	`number`	Number of competitors offering a free trial
`youShowPrice`	`boolean \| null`	Whether you show pricing on your homepage, or null when your own homepage couldn’t be analyzed this run (see `customer.messagingAnalysisAvailable`) — never report a pricing-transparency posture off a null. A measured homepage that genuinely shows no pricing is false, not null. Nullable.
`youHaveFreeTrial`	`boolean \| null`	Whether you offer a free trial, or null when your own homepage couldn’t be analyzed this run (see `customer.messagingAnalysisAvailable`) — never report a free-trial claim off a null. A measured homepage with genuinely no free trial is false, not null. Nullable.

item.competitors[].content — object

Field	Type	Description
`pageTitle`	`string`	Page title
`pageDescription`	`string`	Page meta description
`mainHeadline`	`string`	Main homepage headline
`tagline`	`string`	Tagline or subheadline
`valueProposition`	`string`	Core value proposition statement
`primaryCTA`	`string`	Primary call-to-action text
`secondaryCTA`	`string`	Secondary call-to-action text
`keyOfferings`	`array<string>`	Key product offerings listed on homepage
`targetAudience`	`string`	Target audience as described on homepage
`mainDifferentiator`	`string`	Main differentiator or unique selling point
`pricingMentioned`	`boolean`	Whether pricing is mentioned on the homepage
`startingPrice`	`string`	Starting price if mentioned on homepage
`hasFreeTrial`	`boolean`	Whether a free trial is offered
`freeTrialDuration`	`string`	Free trial duration if offered

item.summary.customer.messagingAnalysisAvailable — object

Field	Type	Description
`available`	`boolean`	Always false for this discriminator.
`reason`	`string`	Why your homepage messaging couldn’t be scored. ‘homepage_fetch_failed’ = we couldn’t retrieve your homepage this run; ‘homepage_url_not_configured’ = no homepage URL is set for your own domain. Values: `homepage_fetch_failed`, `homepage_url_not_configured`.

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
  }
}