Content

REST endpoints for Content. 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 content intelligence data

GET/v1/projects/{projectId}/content

Get the latest content intelligence data for all competitors in a project. Returns URL counts, content categorization, strategic URL analysis, and competitive gap assessment. Use this to understand the content landscape across competitors. 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. The four gap lists carry a distinction worth respecting: a null list means no comparison ran, while an EMPTY list means we compared and found none — reading the first as the second reports a verdict about a comparison that never happened. 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/content" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "item": {
    "lastUpdatedAt": "2026-03-15T10:00:00.000Z",
    "summary": {
      "sitemapsChecked": 8,
      "sitemapsSuccessful": 7,
      "customer": {
        "domain": "yoursite.com",
        "totalUrls": 350,
        "strategicUrls": 280,
        "categorizedCounts": {
          "blog": 120,
          "docs": 80,
          "tools": 5,
          "landing": 30,
          "legal": 10,
          "caseStudies": 0,
          "comparison": 3,
          "integrations": 25,
          "changelog": 15,
          "webinars": 2,
          "other": 60
        },
        "contentAnalysisAvailable": {
          "available": false,
          "reason": "content_fetch_failed"
        }
      },
      "topCompetitor": {
        "domain": "rival.com",
        "strategicUrls": 420
      },
      "strategicUrlGap": -140,
      "overallRank": 3,
      "comparableCompetitors": 4,
      "criticalGaps": [
        {
          "category": "caseStudies",
          "categoryLabel": "Case Studies",
          "competitorsWithContent": 3,
          "leader": {
            "domain": "competitor.com",
            "count": 42,
            "exampleUrls": [
              "https://competitor.com/blog/post-1",
              "https://competitor.com/blog/post-2"
            ]
          },
          "actionHint": "Create 3-5 case studies showcasing customer success stories"
        }
      ],
      "significantGaps": [
        {
          "category": "blog",
          "categoryLabel": "Blog Posts",
          "customerCount": 5,
          "competitorAverage": 25,
          "competitorMax": 42,
          "gapPercentage": -80,
          "leader": {
            "domain": "competitor.com",
            "count": 42,
            "exampleUrls": [
              "https://competitor.com/blog/post-1",
              "https://competitor.com/blog/post-2"
            ]
          },
          "actionHint": "Increase blog output to at least match competitor average of 25 posts"
        }
      ],
      "advantages": [
        {
          "category": "docs",
          "categoryLabel": "Documentation",
          "customerCount": 120,
          "competitorMax": 45,
          "leadAmount": 75
        }
      ],
      "onTrack": [
        {
          "category": "landing",
          "categoryLabel": "Landing Pages",
          "customerCount": 30,
          "competitorMax": 35,
          "differencePercent": -14
        }
      ],
      "totalCriticalGaps": 2,
      "totalSignificantGaps": 1,
      "totalAdvantages": 3,
      "totalOnTrack": 4
    },
    "competitors": [
      {
        "domain": "competitor.com",
        "isOwn": false,
        "totalUrls": 450,
        "strategicUrls": 380,
        "categorizedCounts": {
          "blog": 150,
          "docs": 100,
          "tools": 10,
          "landing": 10,
          "caseStudies": 10,
          "comparison": 10,
          "integrations": 10,
          "changelog": 10,
          "webinars": 10,
          "legal": 10,
          "programmatic": 27996,
          "other": 65
        },
        "programmaticExampleUrls": [
          "https://competitor.com/ncm/01012100",
          "https://competitor.com/cnae/0119-9-01",
          "https://competitor.com/cfop/1101"
        ],
        "sitemapCount": 2,
        "contentDataAvailable": {
          "available": false,
          "reason": "no_sitemap_published"
        }
      }
    ]
  }
}

Fields

item — object

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

item.summary — object

Field	Type	Description
`sitemapsChecked`	`number`	Number of sitemaps checked in this run
`sitemapsSuccessful`	`number`	Number of sitemaps successfully processed
`customer`	`object`	Your domain’s content metrics. See `item.summary.customer`.
`topCompetitor`	`object \| null`	Competitor with the most strategic URLs, or null when no competitor returned usable content data this run — that is the only thing null means here, and it never means the competitors have none. A competitor leading with `strategicUrls: 0` is the opposite case and is a real result: everyone was measured and nobody publishes a strategic page. Nullable. See `item.summary.topCompetitor`.
`strategicUrlGap`	`number \| null`	Your strategic URL count minus the top competitor’s (negative = you are behind), or null when there is no comparison to make: your own sitemap was unmeasured, or no competitor returned usable content data. A 0 means genuinely level. Was a forced 0 before, which read as ‘level with them’ either way. A gap equal to your own count is what a measured field of zeros produces — your largest possible lead, and a finding to report rather than an anomaly to explain away. Nullable.
`overallRank`	`number \| null`	Your rank by strategic content among the sites that returned comparable content data — your own site plus `comparableCompetitors` competitors (field size = comparableCompetitors + 1). Null when fewer than two competitors had usable data, or when your own site returned no usable data to rank. Nullable.
`comparableCompetitors`	`number`	Competitors (excluding your own site) that returned usable content data — the sample size behind the gap and advantage comparisons. The overall rank is taken over this set plus your own site, so the rank’s field size is `comparableCompetitors + 1`.
`criticalGaps`	`array<object> \| null`	Content categories where you have zero content but competitors do. Only the 9 strategic categories are evaluated here: Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars. Legal, Programmatic Pages, Other are counted in `categorizedCounts` but never assessed, so their absence from this list is not a verdict about them. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable. See `item.summary.criticalGaps[]`.
`significantGaps`	`array<object> \| null`	Content categories where you are significantly behind (>50%). Only the 9 strategic categories are evaluated here: Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars. Legal, Programmatic Pages, Other are counted in `categorizedCounts` but never assessed, so their absence from this list is not a verdict about them. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable. See `item.summary.significantGaps[]`.
`advantages`	`array<object> \| null`	Content categories where you lead all competitors. Only the 9 strategic categories are evaluated here: Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars. Legal, Programmatic Pages, Other are counted in `categorizedCounts` but never assessed, so their absence from this list is not a verdict about them. A category missing from this list either wasn’t evaluated or wasn’t led — check it against that set before reporting either. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. A null here in particular must NOT be read as leading in none. Nullable. See `item.summary.advantages[]`.
`onTrack`	`array<object> \| null`	Content categories where you are competitive (within threshold). Only the 9 strategic categories are evaluated here: Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars. Legal, Programmatic Pages, Other are counted in `categorizedCounts` but never assessed, so their absence from this list is not a verdict about them. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable. See `item.summary.onTrack[]`.
`totalCriticalGaps`	`number \| null`	Total number of critical content gaps, out of the 9 strategic categories evaluated. Derived from the list above, so the two are always consistent — including when both are null. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable.
`totalSignificantGaps`	`number \| null`	Total number of significant content gaps, out of the 9 strategic categories evaluated. Derived from the list above, so the two are always consistent. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable.
`totalAdvantages`	`number \| null`	Total number of content advantages, out of the 9 strategic categories evaluated. Derived from the list above, so the two are always consistent. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable.
`totalOnTrack`	`number \| null`	Total number of on-track categories, out of the 9 strategic categories evaluated. Derived from the list above, so the two are always consistent. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable.

item.competitors[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`isOwn`	`boolean`	Whether this is the project’s own domain
`totalUrls`	`number \| null`	Total DISTINCT URLs across this competitor’s sitemaps, or null exactly when `contentDataAvailable` is present (no readable sitemap this run). Never read a null as 0: ‘0 URLs’ is a measured claim about a readable sitemap. Distinct matters and is not a formality — two of a competitor’s stored sitemap locations can resolve to the same set of pages after they reorganise, and each page is counted once regardless. So this figure need not equal the sum of the per-sitemap counts you may see elsewhere, and `sitemapCount` counts the files they publish rather than the ones that contributed here. Do not reconcile the two; this is the page count. Nullable.
`strategicUrls`	`number \| null`	Strategic URLs — the sum over the 9 strategic categories ONLY. Legal, Programmatic Pages, Other are counted in `categorizedCounts` and excluded here, so `totalUrls - strategicUrls` is NOT “legal plus junk” — most of it may be Programmatic Pages, which is a content operation rather than noise. Null exactly when `contentDataAvailable` is present. Nullable.
`categorizedCounts`	`object \| null`	URL counts by content category, or null if categorization unavailable. Keys are the 12 categories we classify into: blog, docs, tools, landing, caseStudies, comparison, integrations, changelog, webinars, legal, programmatic, other. A category ABSENT from the map was not computed for this run — older runs predate categories added since — while a category present with `0` was measured as empty. Those are different facts; do not report an absent key as a zero. Nullable.
`programmaticExampleUrls`	`array<string> \| null`	Up to 5 real URLs sampled from this competitor’s `programmatic` pages, spread across the sections they came from. Empty when the competitor publishes none. Why these ship: the platform reports templated pages WITHOUT judging why a vendor generates them, because a URL shape cannot show intent — for a programmatic-SEO player it is the growth engine, for a reference database it is plumbing. That refusal is only honest if you can settle it yourself, and these URLs do that in seconds. Open two or three before characterising a large `programmatic` count. They are evidence for a count, not a measurement of their own — sampled at read time, never stored, so they may differ between calls. `null` exactly when `contentDataAvailable` is present: we read no sitemap, so there is nothing to sample. An empty ARRAY is the different, measured fact that we read the sitemap and it has no programmatic pages. Nullable.
`sitemapCount`	`number`	Number of READABLE sitemaps this run for this competitor (0 when `contentDataAvailable` is present)
`contentDataAvailable`	`object`	Honest-degradation discriminator (per-competitor). Present only when NO sitemap could be read for this competitor this run — see `reason` for whether that is a measured absence (no working sitemap could be found for them, a claim whose limits `reason` spells out) or our fetch failure. When present, `totalUrls` and `strategicUrls` are null and `categorizedCounts` is null — do not derive any content verdict (e.g. ‘competitor has no blog’) from this row. Absent whenever at least one sitemap was read (the normal path). On the dashboard, rows reflect the latest known state per sitemap, so a fetch failure in a newer, still-running run can briefly mark a row unavailable until that run completes; run-detail rows are scoped to their own run. See `item.competitors[].contentDataAvailable`.

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 comes from your project’s own configuration, not from the sitemap 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.
`totalUrls`	`number \| null`	Total URLs discovered across all your sitemaps, or null when your own sitemap couldn’t be analyzed this run. A `0` is a MEASURED finding — a sitemap we read that lists nothing — so never read a null as 0. Nullable.
`strategicUrls`	`number \| null`	Strategic URLs — the sum over the 9 strategic categories ONLY (Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars). Legal, Programmatic Pages, Other are counted in `categorizedCounts` and excluded here, so `totalUrls - strategicUrls` is NOT “legal plus junk”: on a vendor that generates templated pages at scale, most of that difference is Programmatic Pages — a real content operation — and attributing it to noise understates them badly. Read `categorizedCounts.programmatic` before drawing any conclusion from the difference. Null when your own sitemap couldn’t be analyzed this run. A `0` is a measured finding and the honest floor of the content comparison; a null means we never read the sitemap. Nullable.
`categorizedCounts`	`object \| null`	URL counts per content category, or null when your own sitemap couldn’t be analyzed this run. Nulled as a whole rather than returned all-zero, because an all-zero map reads as “measured, and every category is empty” — a much stronger claim than “we couldn’t look”. The keys are the 12 categories we classify into: blog, docs, tools, landing, caseStudies, comparison, integrations, changelog, webinars, legal, programmatic, other. A category absent from the map has zero URLs; a category present with 0 was measured as empty. Note this map is WIDER than the set the gap analysis evaluates: Legal, Programmatic Pages, Other are counted here but never assessed for gaps, advantages or on-track status, so a category with a count here and no entry in `criticalGaps` / `advantages` / `onTrack` may simply never have been a candidate. `strategicUrls` is the sum over the 9 evaluated ones, not over this whole map. Nullable.
`contentAnalysisAvailable`	`object`	Present ONLY when your own sitemap couldn’t be analyzed this run (fetch failed, or no working sitemap could be found) — see `reason`. When present, every metric in this object is null, `strategicUrlGap` is null, and all four gap lists (`criticalGaps`, `significantGaps`, `advantages`, `onTrack`) and their four count siblings are null. Nothing here is a measured fact; the nulls say so on their own, and this field records why. 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. This flag is a sufficient reason for those eight nulls but NOT a necessary one: they are also null when your own sitemap read fine and no competitor returned usable data (`comparableCompetitors` is 0), with this flag absent — so never conclude from a null gap list alone that YOUR check failed. Note too the difference between a null list and an empty one: `[]` means we compared and found none, which is a real finding. See `item.summary.customer.contentAnalysisAvailable`.

item.summary.topCompetitor — object

Field	Type	Description
`domain`	`string`	Top competitor domain by strategic URLs
`strategicUrls`	`number`	Their strategic URL count. A 0 here is a measurement, not a missing value: every competitor we read was read successfully and none publishes a strategic page. Report it as a leader with zero — usually the customer’s largest lead — never as ‘no data’ or ‘no competitor’.

item.summary.criticalGaps[] — each entry

Field	Type	Description
`category`	`string`	Content category where you have zero content
`categoryLabel`	`string`	Human-readable category name
`competitorsWithContent`	`number`	Number of competitors that have content in this category
`leader`	`object`	Competitor leading in this category. See `item.summary.criticalGaps[].leader`.
`actionHint`	`string`	Actionable guidance for addressing this gap

item.summary.significantGaps[] — each entry

Field	Type	Description
`category`	`string`	Content category where you are significantly behind
`categoryLabel`	`string`	Human-readable category name
`customerCount`	`number`	Your URL count in this category
`competitorAverage`	`number`	Average competitor URL count
`competitorMax`	`number`	Maximum competitor URL count
`gapPercentage`	`number`	How far behind you are as a percentage (negative = behind)
`leader`	`object`	Competitor leading in this category. See `item.summary.significantGaps[].leader`.
`actionHint`	`string`	Actionable guidance for addressing this gap

item.summary.advantages[] — each entry

Field	Type	Description
`category`	`string`	Content category where you lead
`categoryLabel`	`string`	Human-readable category name
`customerCount`	`number`	Your URL count in this category
`competitorMax`	`number`	Maximum competitor URL count
`leadAmount`	`number`	How many more URLs you have than the best competitor

item.summary.onTrack[] — each entry

Field	Type	Description
`category`	`string`	Content category where you are competitive
`categoryLabel`	`string`	Human-readable category name
`customerCount`	`number`	Your URL count in this category
`competitorMax`	`number`	Maximum competitor URL count
`differencePercent`	`number`	Percentage difference from the best competitor

item.competitors[].contentDataAvailable — object

Field	Type	Description
`available`	`boolean`	Always false — present only when this competitor row carries no content data
`reason`	`string`	Why this competitor’s content couldn’t be counted this run. ‘no_sitemap_published’ = no working sitemap was found for them — nothing was discovered, or every location we know of returns 404. Read it as ‘nothing findable where we look’, not as proof they publish none: we re-discover sitemap locations periodically, so a competitor who has MOVED theirs reads this way until we re-check. What it does support is that their content is currently invisible to sitemap-based analysis, and to sitemap-reading crawlers. ‘sitemap_fetch_failed’ = our fetch or parse failed this run — nothing was measured, so no verdict about the competitor’s content may be derived from this row. On the dashboard this reflects the latest known fetch state — a newer run’s in-flight failure can briefly surface here until that run completes; in run-detail responses the reason is scoped to that run. Values: `no_sitemap_published`, `sitemap_fetch_failed`.

item.summary.customer.contentAnalysisAvailable — object

Field	Type	Description
`available`	`boolean`	Always false — present only when your own content could not be analyzed
`reason`	`string`	Why your own content is unmeasured this run. ‘content_fetch_failed’ = your sitemap couldn’t be read; ‘content_url_not_configured’ = no working sitemap could be found for your own domain — none was discovered, or the ones we hold no longer resolve. It describes what we could not find, not something you failed to set up: sitemap locations are re-discovered periodically, so a site that reorganises its sitemaps reads this way until the next re-discovery. Values: `content_fetch_failed`, `content_url_not_configured`.

item.summary.criticalGaps[].leader — object

Field	Type	Description
`domain`	`string`	Leader competitor domain
`count`	`number`	Number of URLs in this category
`exampleUrls`	`array<string>`	Example URLs for inspiration (3-5)

item.summary.significantGaps[].leader — object

Field	Type	Description
`domain`	`string`	Leader competitor domain
`count`	`number`	Number of URLs in this category
`exampleUrls`	`array<string>`	Example URLs for inspiration (3-5)

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 content intelligence run history

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

Get paginated history of content intelligence monitoring runs for a project. Each entry includes run timing and summary statistics with 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/content/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": {
        "sitemapsChecked": 8,
        "sitemapsSuccessful": 7,
        "customer": {
          "domain": "yoursite.com",
          "totalUrls": 350,
          "strategicUrls": 280,
          "categorizedCounts": {
            "blog": 120,
            "docs": 80,
            "tools": 5,
            "landing": 30,
            "legal": 10,
            "caseStudies": 0,
            "comparison": 3,
            "integrations": 25,
            "changelog": 15,
            "webinars": 2,
            "other": 60
          },
          "contentAnalysisAvailable": {
            "available": false,
            "reason": "content_fetch_failed"
          }
        },
        "topCompetitor": {
          "domain": "rival.com",
          "strategicUrls": 420
        },
        "strategicUrlGap": -140,
        "overallRank": 3,
        "comparableCompetitors": 4,
        "criticalGaps": [
          {
            "category": "caseStudies",
            "categoryLabel": "Case Studies",
            "competitorsWithContent": 3,
            "leader": {
              "domain": "competitor.com",
              "count": 42,
              "exampleUrls": [
                "https://competitor.com/blog/post-1",
                "https://competitor.com/blog/post-2"
              ]
            },
            "actionHint": "Create 3-5 case studies showcasing customer success stories"
          }
        ],
        "significantGaps": [
          {
            "category": "blog",
            "categoryLabel": "Blog Posts",
            "customerCount": 5,
            "competitorAverage": 25,
            "competitorMax": 42,
            "gapPercentage": -80,
            "leader": {
              "domain": "competitor.com",
              "count": 42,
              "exampleUrls": [
                "https://competitor.com/blog/post-1",
                "https://competitor.com/blog/post-2"
              ]
            },
            "actionHint": "Increase blog output to at least match competitor average of 25 posts"
          }
        ],
        "advantages": [
          {
            "category": "docs",
            "categoryLabel": "Documentation",
            "customerCount": 120,
            "competitorMax": 45,
            "leadAmount": 75
          }
        ],
        "onTrack": [
          {
            "category": "landing",
            "categoryLabel": "Landing Pages",
            "customerCount": 30,
            "competitorMax": 35,
            "differencePercent": -14
          }
        ],
        "totalCriticalGaps": 2,
        "totalSignificantGaps": 1,
        "totalAdvantages": 3,
        "totalOnTrack": 4
      }
    }
  ],
  "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
`sitemapsChecked`	`number`	Number of sitemaps checked in this run
`sitemapsSuccessful`	`number`	Number of sitemaps successfully processed
`customer`	`object`	Your domain’s content metrics. See `items[].summary.customer`.
`topCompetitor`	`object \| null`	Competitor with the most strategic URLs, or null when no competitor returned usable content data this run — that is the only thing null means here, and it never means the competitors have none. A competitor leading with `strategicUrls: 0` is the opposite case and is a real result: everyone was measured and nobody publishes a strategic page. Nullable. See `items[].summary.topCompetitor`.
`strategicUrlGap`	`number \| null`	Your strategic URL count minus the top competitor’s (negative = you are behind), or null when there is no comparison to make: your own sitemap was unmeasured, or no competitor returned usable content data. A 0 means genuinely level. Was a forced 0 before, which read as ‘level with them’ either way. A gap equal to your own count is what a measured field of zeros produces — your largest possible lead, and a finding to report rather than an anomaly to explain away. Nullable.
`overallRank`	`number \| null`	Your rank by strategic content among the sites that returned comparable content data — your own site plus `comparableCompetitors` competitors (field size = comparableCompetitors + 1). Null when fewer than two competitors had usable data, or when your own site returned no usable data to rank. Nullable.
`comparableCompetitors`	`number`	Competitors (excluding your own site) that returned usable content data — the sample size behind the gap and advantage comparisons. The overall rank is taken over this set plus your own site, so the rank’s field size is `comparableCompetitors + 1`.
`criticalGaps`	`array<object> \| null`	Content categories where you have zero content but competitors do. Only the 9 strategic categories are evaluated here: Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars. Legal, Programmatic Pages, Other are counted in `categorizedCounts` but never assessed, so their absence from this list is not a verdict about them. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable. See `items[].summary.criticalGaps[]`.
`significantGaps`	`array<object> \| null`	Content categories where you are significantly behind (>50%). Only the 9 strategic categories are evaluated here: Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars. Legal, Programmatic Pages, Other are counted in `categorizedCounts` but never assessed, so their absence from this list is not a verdict about them. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable. See `items[].summary.significantGaps[]`.
`advantages`	`array<object> \| null`	Content categories where you lead all competitors. Only the 9 strategic categories are evaluated here: Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars. Legal, Programmatic Pages, Other are counted in `categorizedCounts` but never assessed, so their absence from this list is not a verdict about them. A category missing from this list either wasn’t evaluated or wasn’t led — check it against that set before reporting either. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. A null here in particular must NOT be read as leading in none. Nullable. See `items[].summary.advantages[]`.
`onTrack`	`array<object> \| null`	Content categories where you are competitive (within threshold). Only the 9 strategic categories are evaluated here: Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars. Legal, Programmatic Pages, Other are counted in `categorizedCounts` but never assessed, so their absence from this list is not a verdict about them. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable. See `items[].summary.onTrack[]`.
`totalCriticalGaps`	`number \| null`	Total number of critical content gaps, out of the 9 strategic categories evaluated. Derived from the list above, so the two are always consistent — including when both are null. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable.
`totalSignificantGaps`	`number \| null`	Total number of significant content gaps, out of the 9 strategic categories evaluated. Derived from the list above, so the two are always consistent. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable.
`totalAdvantages`	`number \| null`	Total number of content advantages, out of the 9 strategic categories evaluated. Derived from the list above, so the two are always consistent. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable.
`totalOnTrack`	`number \| null`	Total number of on-track categories, out of the 9 strategic categories evaluated. Derived from the list above, so the two are always consistent. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable.

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 comes from your project’s own configuration, not from the sitemap 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.
`totalUrls`	`number \| null`	Total URLs discovered across all your sitemaps, or null when your own sitemap couldn’t be analyzed this run. A `0` is a MEASURED finding — a sitemap we read that lists nothing — so never read a null as 0. Nullable.
`strategicUrls`	`number \| null`	Strategic URLs — the sum over the 9 strategic categories ONLY (Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars). Legal, Programmatic Pages, Other are counted in `categorizedCounts` and excluded here, so `totalUrls - strategicUrls` is NOT “legal plus junk”: on a vendor that generates templated pages at scale, most of that difference is Programmatic Pages — a real content operation — and attributing it to noise understates them badly. Read `categorizedCounts.programmatic` before drawing any conclusion from the difference. Null when your own sitemap couldn’t be analyzed this run. A `0` is a measured finding and the honest floor of the content comparison; a null means we never read the sitemap. Nullable.
`categorizedCounts`	`object \| null`	URL counts per content category, or null when your own sitemap couldn’t be analyzed this run. Nulled as a whole rather than returned all-zero, because an all-zero map reads as “measured, and every category is empty” — a much stronger claim than “we couldn’t look”. The keys are the 12 categories we classify into: blog, docs, tools, landing, caseStudies, comparison, integrations, changelog, webinars, legal, programmatic, other. A category absent from the map has zero URLs; a category present with 0 was measured as empty. Note this map is WIDER than the set the gap analysis evaluates: Legal, Programmatic Pages, Other are counted here but never assessed for gaps, advantages or on-track status, so a category with a count here and no entry in `criticalGaps` / `advantages` / `onTrack` may simply never have been a candidate. `strategicUrls` is the sum over the 9 evaluated ones, not over this whole map. Nullable.
`contentAnalysisAvailable`	`object`	Present ONLY when your own sitemap couldn’t be analyzed this run (fetch failed, or no working sitemap could be found) — see `reason`. When present, every metric in this object is null, `strategicUrlGap` is null, and all four gap lists (`criticalGaps`, `significantGaps`, `advantages`, `onTrack`) and their four count siblings are null. Nothing here is a measured fact; the nulls say so on their own, and this field records why. 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. This flag is a sufficient reason for those eight nulls but NOT a necessary one: they are also null when your own sitemap read fine and no competitor returned usable data (`comparableCompetitors` is 0), with this flag absent — so never conclude from a null gap list alone that YOUR check failed. Note too the difference between a null list and an empty one: `[]` means we compared and found none, which is a real finding. See `items[].summary.customer.contentAnalysisAvailable`.

items[].summary.topCompetitor — object

Field	Type	Description
`domain`	`string`	Top competitor domain by strategic URLs
`strategicUrls`	`number`	Their strategic URL count. A 0 here is a measurement, not a missing value: every competitor we read was read successfully and none publishes a strategic page. Report it as a leader with zero — usually the customer’s largest lead — never as ‘no data’ or ‘no competitor’.

items[].summary.criticalGaps[] — each entry

Field	Type	Description
`category`	`string`	Content category where you have zero content
`categoryLabel`	`string`	Human-readable category name
`competitorsWithContent`	`number`	Number of competitors that have content in this category
`leader`	`object`	Competitor leading in this category. See `items[].summary.criticalGaps[].leader`.
`actionHint`	`string`	Actionable guidance for addressing this gap

items[].summary.significantGaps[] — each entry

Field	Type	Description
`category`	`string`	Content category where you are significantly behind
`categoryLabel`	`string`	Human-readable category name
`customerCount`	`number`	Your URL count in this category
`competitorAverage`	`number`	Average competitor URL count
`competitorMax`	`number`	Maximum competitor URL count
`gapPercentage`	`number`	How far behind you are as a percentage (negative = behind)
`leader`	`object`	Competitor leading in this category. See `items[].summary.significantGaps[].leader`.
`actionHint`	`string`	Actionable guidance for addressing this gap

items[].summary.advantages[] — each entry

Field	Type	Description
`category`	`string`	Content category where you lead
`categoryLabel`	`string`	Human-readable category name
`customerCount`	`number`	Your URL count in this category
`competitorMax`	`number`	Maximum competitor URL count
`leadAmount`	`number`	How many more URLs you have than the best competitor

items[].summary.onTrack[] — each entry

Field	Type	Description
`category`	`string`	Content category where you are competitive
`categoryLabel`	`string`	Human-readable category name
`customerCount`	`number`	Your URL count in this category
`competitorMax`	`number`	Maximum competitor URL count
`differencePercent`	`number`	Percentage difference from the best competitor

items[].summary.customer.contentAnalysisAvailable — object

Field	Type	Description
`available`	`boolean`	Always false — present only when your own content could not be analyzed
`reason`	`string`	Why your own content is unmeasured this run. ‘content_fetch_failed’ = your sitemap couldn’t be read; ‘content_url_not_configured’ = no working sitemap could be found for your own domain — none was discovered, or the ones we hold no longer resolve. It describes what we could not find, not something you failed to set up: sitemap locations are re-discovered periodically, so a site that reorganises its sitemaps reads this way until the next re-discovery. Values: `content_fetch_failed`, `content_url_not_configured`.

items[].summary.criticalGaps[].leader — object

Field	Type	Description
`domain`	`string`	Leader competitor domain
`count`	`number`	Number of URLs in this category
`exampleUrls`	`array<string>`	Example URLs for inspiration (3-5)

items[].summary.significantGaps[].leader — object

Field	Type	Description
`domain`	`string`	Leader competitor domain
`count`	`number`	Number of URLs in this category
`exampleUrls`	`array<string>`	Example URLs for inspiration (3-5)

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 content intelligence data for a specific run

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

Get full content intelligence data for a specific historical monitoring run, including per-competitor URL counts, content categorization, and strategic URL metrics. 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/content/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": {
      "sitemapsChecked": 8,
      "sitemapsSuccessful": 7,
      "customer": {
        "domain": "yoursite.com",
        "totalUrls": 350,
        "strategicUrls": 280,
        "categorizedCounts": {
          "blog": 120,
          "docs": 80,
          "tools": 5,
          "landing": 30,
          "legal": 10,
          "caseStudies": 0,
          "comparison": 3,
          "integrations": 25,
          "changelog": 15,
          "webinars": 2,
          "other": 60
        },
        "contentAnalysisAvailable": {
          "available": false,
          "reason": "content_fetch_failed"
        }
      },
      "topCompetitor": {
        "domain": "rival.com",
        "strategicUrls": 420
      },
      "strategicUrlGap": -140,
      "overallRank": 3,
      "comparableCompetitors": 4,
      "criticalGaps": [
        {
          "category": "caseStudies",
          "categoryLabel": "Case Studies",
          "competitorsWithContent": 3,
          "leader": {
            "domain": "competitor.com",
            "count": 42,
            "exampleUrls": [
              "https://competitor.com/blog/post-1",
              "https://competitor.com/blog/post-2"
            ]
          },
          "actionHint": "Create 3-5 case studies showcasing customer success stories"
        }
      ],
      "significantGaps": [
        {
          "category": "blog",
          "categoryLabel": "Blog Posts",
          "customerCount": 5,
          "competitorAverage": 25,
          "competitorMax": 42,
          "gapPercentage": -80,
          "leader": {
            "domain": "competitor.com",
            "count": 42,
            "exampleUrls": [
              "https://competitor.com/blog/post-1",
              "https://competitor.com/blog/post-2"
            ]
          },
          "actionHint": "Increase blog output to at least match competitor average of 25 posts"
        }
      ],
      "advantages": [
        {
          "category": "docs",
          "categoryLabel": "Documentation",
          "customerCount": 120,
          "competitorMax": 45,
          "leadAmount": 75
        }
      ],
      "onTrack": [
        {
          "category": "landing",
          "categoryLabel": "Landing Pages",
          "customerCount": 30,
          "competitorMax": 35,
          "differencePercent": -14
        }
      ],
      "totalCriticalGaps": 2,
      "totalSignificantGaps": 1,
      "totalAdvantages": 3,
      "totalOnTrack": 4
    },
    "competitors": [
      {
        "domain": "competitor.com",
        "isOwn": false,
        "totalUrls": 450,
        "strategicUrls": 380,
        "categorizedCounts": {
          "blog": 150,
          "docs": 100,
          "tools": 10,
          "landing": 10,
          "caseStudies": 10,
          "comparison": 10,
          "integrations": 10,
          "changelog": 10,
          "webinars": 10,
          "legal": 10,
          "programmatic": 27996,
          "other": 65
        },
        "programmaticExampleUrls": [
          "https://competitor.com/ncm/01012100",
          "https://competitor.com/cnae/0119-9-01",
          "https://competitor.com/cfop/1101"
        ],
        "sitemapCount": 2,
        "contentDataAvailable": {
          "available": false,
          "reason": "no_sitemap_published"
        }
      }
    ]
  }
}

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

item.summary — object

Field	Type	Description
`sitemapsChecked`	`number`	Number of sitemaps checked in this run
`sitemapsSuccessful`	`number`	Number of sitemaps successfully processed
`customer`	`object`	Your domain’s content metrics. See `item.summary.customer`.
`topCompetitor`	`object \| null`	Competitor with the most strategic URLs, or null when no competitor returned usable content data this run — that is the only thing null means here, and it never means the competitors have none. A competitor leading with `strategicUrls: 0` is the opposite case and is a real result: everyone was measured and nobody publishes a strategic page. Nullable. See `item.summary.topCompetitor`.
`strategicUrlGap`	`number \| null`	Your strategic URL count minus the top competitor’s (negative = you are behind), or null when there is no comparison to make: your own sitemap was unmeasured, or no competitor returned usable content data. A 0 means genuinely level. Was a forced 0 before, which read as ‘level with them’ either way. A gap equal to your own count is what a measured field of zeros produces — your largest possible lead, and a finding to report rather than an anomaly to explain away. Nullable.
`overallRank`	`number \| null`	Your rank by strategic content among the sites that returned comparable content data — your own site plus `comparableCompetitors` competitors (field size = comparableCompetitors + 1). Null when fewer than two competitors had usable data, or when your own site returned no usable data to rank. Nullable.
`comparableCompetitors`	`number`	Competitors (excluding your own site) that returned usable content data — the sample size behind the gap and advantage comparisons. The overall rank is taken over this set plus your own site, so the rank’s field size is `comparableCompetitors + 1`.
`criticalGaps`	`array<object> \| null`	Content categories where you have zero content but competitors do. Only the 9 strategic categories are evaluated here: Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars. Legal, Programmatic Pages, Other are counted in `categorizedCounts` but never assessed, so their absence from this list is not a verdict about them. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable. See `item.summary.criticalGaps[]`.
`significantGaps`	`array<object> \| null`	Content categories where you are significantly behind (>50%). Only the 9 strategic categories are evaluated here: Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars. Legal, Programmatic Pages, Other are counted in `categorizedCounts` but never assessed, so their absence from this list is not a verdict about them. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable. See `item.summary.significantGaps[]`.
`advantages`	`array<object> \| null`	Content categories where you lead all competitors. Only the 9 strategic categories are evaluated here: Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars. Legal, Programmatic Pages, Other are counted in `categorizedCounts` but never assessed, so their absence from this list is not a verdict about them. A category missing from this list either wasn’t evaluated or wasn’t led — check it against that set before reporting either. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. A null here in particular must NOT be read as leading in none. Nullable. See `item.summary.advantages[]`.
`onTrack`	`array<object> \| null`	Content categories where you are competitive (within threshold). Only the 9 strategic categories are evaluated here: Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars. Legal, Programmatic Pages, Other are counted in `categorizedCounts` but never assessed, so their absence from this list is not a verdict about them. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable. See `item.summary.onTrack[]`.
`totalCriticalGaps`	`number \| null`	Total number of critical content gaps, out of the 9 strategic categories evaluated. Derived from the list above, so the two are always consistent — including when both are null. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable.
`totalSignificantGaps`	`number \| null`	Total number of significant content gaps, out of the 9 strategic categories evaluated. Derived from the list above, so the two are always consistent. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable.
`totalAdvantages`	`number \| null`	Total number of content advantages, out of the 9 strategic categories evaluated. Derived from the list above, so the two are always consistent. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable.
`totalOnTrack`	`number \| null`	Total number of on-track categories, out of the 9 strategic categories evaluated. Derived from the list above, so the two are always consistent. Null in TWO cases, and they are different facts you must not report as the same one: your own sitemap couldn’t be analyzed this run (`customer.contentAnalysisAvailable` is present — our reach into YOUR site), or no competitor returned usable content data (`comparableCompetitors` is 0 — our reach into THEIRS, with your own site measured fine). Check both before saying whose check failed. An empty array is neither: it means we compared and found none, which is a real finding. Nullable.

item.competitors[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`isOwn`	`boolean`	Whether this is the project’s own domain
`totalUrls`	`number \| null`	Total DISTINCT URLs across this competitor’s sitemaps, or null exactly when `contentDataAvailable` is present (no readable sitemap this run). Never read a null as 0: ‘0 URLs’ is a measured claim about a readable sitemap. Distinct matters and is not a formality — two of a competitor’s stored sitemap locations can resolve to the same set of pages after they reorganise, and each page is counted once regardless. So this figure need not equal the sum of the per-sitemap counts you may see elsewhere, and `sitemapCount` counts the files they publish rather than the ones that contributed here. Do not reconcile the two; this is the page count. Nullable.
`strategicUrls`	`number \| null`	Strategic URLs — the sum over the 9 strategic categories ONLY. Legal, Programmatic Pages, Other are counted in `categorizedCounts` and excluded here, so `totalUrls - strategicUrls` is NOT “legal plus junk” — most of it may be Programmatic Pages, which is a content operation rather than noise. Null exactly when `contentDataAvailable` is present. Nullable.
`categorizedCounts`	`object \| null`	URL counts by content category, or null if categorization unavailable. Keys are the 12 categories we classify into: blog, docs, tools, landing, caseStudies, comparison, integrations, changelog, webinars, legal, programmatic, other. A category ABSENT from the map was not computed for this run — older runs predate categories added since — while a category present with `0` was measured as empty. Those are different facts; do not report an absent key as a zero. Nullable.
`programmaticExampleUrls`	`array<string> \| null`	Up to 5 real URLs sampled from this competitor’s `programmatic` pages, spread across the sections they came from. Empty when the competitor publishes none. Why these ship: the platform reports templated pages WITHOUT judging why a vendor generates them, because a URL shape cannot show intent — for a programmatic-SEO player it is the growth engine, for a reference database it is plumbing. That refusal is only honest if you can settle it yourself, and these URLs do that in seconds. Open two or three before characterising a large `programmatic` count. They are evidence for a count, not a measurement of their own — sampled at read time, never stored, so they may differ between calls. `null` exactly when `contentDataAvailable` is present: we read no sitemap, so there is nothing to sample. An empty ARRAY is the different, measured fact that we read the sitemap and it has no programmatic pages. Nullable.
`sitemapCount`	`number`	Number of READABLE sitemaps this run for this competitor (0 when `contentDataAvailable` is present)
`contentDataAvailable`	`object`	Honest-degradation discriminator (per-competitor). Present only when NO sitemap could be read for this competitor this run — see `reason` for whether that is a measured absence (no working sitemap could be found for them, a claim whose limits `reason` spells out) or our fetch failure. When present, `totalUrls` and `strategicUrls` are null and `categorizedCounts` is null — do not derive any content verdict (e.g. ‘competitor has no blog’) from this row. Absent whenever at least one sitemap was read (the normal path). On the dashboard, rows reflect the latest known state per sitemap, so a fetch failure in a newer, still-running run can briefly mark a row unavailable until that run completes; run-detail rows are scoped to their own run. See `item.competitors[].contentDataAvailable`.

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 comes from your project’s own configuration, not from the sitemap 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.
`totalUrls`	`number \| null`	Total URLs discovered across all your sitemaps, or null when your own sitemap couldn’t be analyzed this run. A `0` is a MEASURED finding — a sitemap we read that lists nothing — so never read a null as 0. Nullable.
`strategicUrls`	`number \| null`	Strategic URLs — the sum over the 9 strategic categories ONLY (Blog Posts, Documentation, Free Tools, Landing Pages, Case Studies, Comparison Pages, Integrations, Changelog, Webinars). Legal, Programmatic Pages, Other are counted in `categorizedCounts` and excluded here, so `totalUrls - strategicUrls` is NOT “legal plus junk”: on a vendor that generates templated pages at scale, most of that difference is Programmatic Pages — a real content operation — and attributing it to noise understates them badly. Read `categorizedCounts.programmatic` before drawing any conclusion from the difference. Null when your own sitemap couldn’t be analyzed this run. A `0` is a measured finding and the honest floor of the content comparison; a null means we never read the sitemap. Nullable.
`categorizedCounts`	`object \| null`	URL counts per content category, or null when your own sitemap couldn’t be analyzed this run. Nulled as a whole rather than returned all-zero, because an all-zero map reads as “measured, and every category is empty” — a much stronger claim than “we couldn’t look”. The keys are the 12 categories we classify into: blog, docs, tools, landing, caseStudies, comparison, integrations, changelog, webinars, legal, programmatic, other. A category absent from the map has zero URLs; a category present with 0 was measured as empty. Note this map is WIDER than the set the gap analysis evaluates: Legal, Programmatic Pages, Other are counted here but never assessed for gaps, advantages or on-track status, so a category with a count here and no entry in `criticalGaps` / `advantages` / `onTrack` may simply never have been a candidate. `strategicUrls` is the sum over the 9 evaluated ones, not over this whole map. Nullable.
`contentAnalysisAvailable`	`object`	Present ONLY when your own sitemap couldn’t be analyzed this run (fetch failed, or no working sitemap could be found) — see `reason`. When present, every metric in this object is null, `strategicUrlGap` is null, and all four gap lists (`criticalGaps`, `significantGaps`, `advantages`, `onTrack`) and their four count siblings are null. Nothing here is a measured fact; the nulls say so on their own, and this field records why. 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. This flag is a sufficient reason for those eight nulls but NOT a necessary one: they are also null when your own sitemap read fine and no competitor returned usable data (`comparableCompetitors` is 0), with this flag absent — so never conclude from a null gap list alone that YOUR check failed. Note too the difference between a null list and an empty one: `[]` means we compared and found none, which is a real finding. See `item.summary.customer.contentAnalysisAvailable`.

item.summary.topCompetitor — object

Field	Type	Description
`domain`	`string`	Top competitor domain by strategic URLs
`strategicUrls`	`number`	Their strategic URL count. A 0 here is a measurement, not a missing value: every competitor we read was read successfully and none publishes a strategic page. Report it as a leader with zero — usually the customer’s largest lead — never as ‘no data’ or ‘no competitor’.

item.summary.criticalGaps[] — each entry

Field	Type	Description
`category`	`string`	Content category where you have zero content
`categoryLabel`	`string`	Human-readable category name
`competitorsWithContent`	`number`	Number of competitors that have content in this category
`leader`	`object`	Competitor leading in this category. See `item.summary.criticalGaps[].leader`.
`actionHint`	`string`	Actionable guidance for addressing this gap

item.summary.significantGaps[] — each entry

Field	Type	Description
`category`	`string`	Content category where you are significantly behind
`categoryLabel`	`string`	Human-readable category name
`customerCount`	`number`	Your URL count in this category
`competitorAverage`	`number`	Average competitor URL count
`competitorMax`	`number`	Maximum competitor URL count
`gapPercentage`	`number`	How far behind you are as a percentage (negative = behind)
`leader`	`object`	Competitor leading in this category. See `item.summary.significantGaps[].leader`.
`actionHint`	`string`	Actionable guidance for addressing this gap

item.summary.advantages[] — each entry

Field	Type	Description
`category`	`string`	Content category where you lead
`categoryLabel`	`string`	Human-readable category name
`customerCount`	`number`	Your URL count in this category
`competitorMax`	`number`	Maximum competitor URL count
`leadAmount`	`number`	How many more URLs you have than the best competitor

item.summary.onTrack[] — each entry

Field	Type	Description
`category`	`string`	Content category where you are competitive
`categoryLabel`	`string`	Human-readable category name
`customerCount`	`number`	Your URL count in this category
`competitorMax`	`number`	Maximum competitor URL count
`differencePercent`	`number`	Percentage difference from the best competitor

item.competitors[].contentDataAvailable — object

Field	Type	Description
`available`	`boolean`	Always false — present only when this competitor row carries no content data
`reason`	`string`	Why this competitor’s content couldn’t be counted this run. ‘no_sitemap_published’ = no working sitemap was found for them — nothing was discovered, or every location we know of returns 404. Read it as ‘nothing findable where we look’, not as proof they publish none: we re-discover sitemap locations periodically, so a competitor who has MOVED theirs reads this way until we re-check. What it does support is that their content is currently invisible to sitemap-based analysis, and to sitemap-reading crawlers. ‘sitemap_fetch_failed’ = our fetch or parse failed this run — nothing was measured, so no verdict about the competitor’s content may be derived from this row. On the dashboard this reflects the latest known fetch state — a newer run’s in-flight failure can briefly surface here until that run completes; in run-detail responses the reason is scoped to that run. Values: `no_sitemap_published`, `sitemap_fetch_failed`.

item.summary.customer.contentAnalysisAvailable — object

Field	Type	Description
`available`	`boolean`	Always false — present only when your own content could not be analyzed
`reason`	`string`	Why your own content is unmeasured this run. ‘content_fetch_failed’ = your sitemap couldn’t be read; ‘content_url_not_configured’ = no working sitemap could be found for your own domain — none was discovered, or the ones we hold no longer resolve. It describes what we could not find, not something you failed to set up: sitemap locations are re-discovered periodically, so a site that reorganises its sitemaps reads this way until the next re-discovery. Values: `content_fetch_failed`, `content_url_not_configured`.

item.summary.criticalGaps[].leader — object

Field	Type	Description
`domain`	`string`	Leader competitor domain
`count`	`number`	Number of URLs in this category
`exampleUrls`	`array<string>`	Example URLs for inspiration (3-5)

item.summary.significantGaps[].leader — object

Field	Type	Description
`domain`	`string`	Leader competitor domain
`count`	`number`	Number of URLs in this category
`exampleUrls`	`array<string>`	Example URLs for inspiration (3-5)

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

Get content changelog

GET/v1/projects/{projectId}/content/changelog

Get paginated changelog of detected URL changes across competitor sitemaps. Each item shows numeric counts per category plus up to 3 sample URLs per category by default — safe for any token budget. Supports filtering by competitorId and category query parameters. Pass allUrlsPerCategory=true for the full URL list per category (warning: high-activity competitors can produce large responses; combine with filters to scope, and check the truncated flag in the response — when true, the byte cap fired and items/URLs were trimmed).

Returns · { items, pagination, truncated }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Query parameters

Name	Type	Description
`page`	`number`	Page number (1-indexed). Default `1`. Min `1`.
`limit`	`number`	Number of items per page. Default `20`. Range `1`–`100`.
`competitorId`	`string`	Filter by competitor ID
`category`	`string`	Filter by content category (blog, docs, tools, landing, caseStudies, comparison, integrations, changelog, webinars, legal, programmatic, other). Changelog rows carry the same category the content dashboard reports for the same URL, decided over the competitor’s whole sitemap rather than over the changed URLs alone — so a page added into a templated catalog filters under `programmatic`, not `other`. Values: `blog`, `docs`, `tools`, `landing`, `caseStudies`, `comparison`, `integrations`, `changelog`, `webinars`, `legal`, `programmatic`, `other`.
`allUrlsPerCategory`	`boolean`	By default each item returns up to 3 sample URLs per category. Set true to return the full URL list per category. High-activity competitors can produce large responses — combine with `category` and `competitorId` filters to scope. Subject to an internal byte cap; check `truncated` in the response.

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/content/changelog?page=1&limit=20&competitorId=507f1f77bcf86cd799439011&category=blog&allUrlsPerCategory=false" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "items": [
    {
      "competitorDomain": "competitor.com",
      "sitemapUrl": "https://competitor.com/sitemap.xml",
      "checkedAt": "2026-03-15T10:00:00.000Z",
      "totalAdded": 5,
      "totalRemoved": 2,
      "addedByCategory": {
        "blog": [
          "https://competitor.com/blog/new-post"
        ],
        "docs": [
          "https://competitor.com/docs/new-guide"
        ],
        "programmatic": [
          "https://competitor.com/ncm/01012100"
        ]
      },
      "removedByCategory": {
        "landing": [
          "https://competitor.com/old-landing"
        ]
      },
      "addedCounts": {
        "blog": 1,
        "docs": 1
      },
      "removedCounts": {
        "landing": 1
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "totalPages": 3,
    "hasMore": true
  },
  "truncated": false
}

Field	Type	Description
`competitorDomain`	`string`	Competitor domain
`sitemapUrl`	`string`	Sitemap URL where changes were detected
`checkedAt`	`string`	When this change was detected (ISO-8601)
`totalAdded`	`number`	Total number of URLs added
`totalRemoved`	`number`	Total number of URLs removed
`addedByCategory`	`object`	Added URLs grouped by content category. Categories are the same ones the content dashboard reports, decided over the competitor’s whole sitemap rather than over these URLs alone — so a page added into a templated catalog arrives as `programmatic`, matching what the dashboard says about the same page. By default each category is capped at 3 sample URLs (numeric totals remain accurate via `addedCounts`). Pass `allUrlsPerCategory=true` to return full URL lists.
`removedByCategory`	`object`	Removed URLs grouped by content category, decided over the sitemap the URL was removed FROM. By default each category is capped at 3 sample URLs (numeric totals remain accurate via `removedCounts`). Pass `allUrlsPerCategory=true` to return full URL lists.
`addedCounts`	`object`	Count of added URLs per category
`removedCounts`	`object`	Count of removed URLs per category

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