Alerts

REST endpoints for Alerts. 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 }.

List project alerts

GET/v1/projects/{projectId}/alerts

Get paginated competitive intelligence alerts for a project. Returns alerts generated when monitoring detects meaningful changes in competitor activity — such as pricing restructures, content strategy shifts, or technology stack changes. Supports filtering by monitoring dimension (tech-trust, content, positioning, pricing, ai-visibility), severity level (critical, high, medium, info), and specific competitor. Alerts are sorted by creation date (newest first).

Returns · { items, pagination }

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`.
`dimension`	`string`	Filter by monitoring dimension (tech-trust, content, positioning, pricing, ai-visibility). Values: `tech-trust`, `content`, `positioning`, `pricing`, `ai-visibility`.
`severity`	`string`	Filter by alert severity (critical, high, medium, info). Values: `critical`, `high`, `medium`, `info`.
`competitorId`	`string`	Filter by competitor ID

Request


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

Response 200 OK

Example


{
  "items": [
    {
      "id": "507f1f77bcf86cd799439011",
      "dimension": "pricing",
      "competitorDomain": "competitor.com",
      "competitorId": "507f1f77bcf86cd799439012",
      "severity": "high",
      "title": "Pricing plan restructure detected",
      "actionHint": "Review your pricing strategy to stay competitive",
      "gapWarnings": [
        "Missing free tier",
        "No annual billing discount"
      ],
      "runId": "507f1f77bcf86cd799439013",
      "alertType": "price_change",
      "context": {},
      "createdAt": "2026-03-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "totalPages": 3,
    "hasMore": true
  }
}

Field	Type	Description
`id`	`string`	Alert ID
`dimension`	`string`	Monitoring dimension that generated this alert. Values: `tech-trust`, `content`, `positioning`, `pricing`, `ai-visibility`.
`competitorDomain`	`string`	Competitor domain
`competitorId`	`string`	Competitor ID
`severity`	`string`	Alert severity level. Values: `critical`, `high`, `medium`, `info`.
`title`	`string`	Alert title describing the detected change
`actionHint`	`string`	Suggested action for the user
`gapWarnings`	`array<string>`	Specific competitive gap warnings
`runId`	`string`	ID of the monitoring run that generated this alert. Use with the dimension’s history endpoint (e.g., GET /v1/projects/{projectId}/pricing/history/{runId}) to retrieve the full data from that monitoring cycle.
`alertType`	`string`	Alert sub-type classifier. Values vary by dimension — e.g., price_change, plan_restructure, feature_toggle (pricing), messaging_shift, positioning_change (positioning), content_growth, content_removal (content), tech_stack_evolution, crawl_strategy (tech-trust), score_shift, provider_change (ai-visibility).
`context`	`object`	Dimension-specific context, keyed by the canonical dimension slug — identical to the `dimension` field (e.g. an ai-visibility alert has an `ai-visibility` key), so you can index context[dimension]. Always present (an empty object when the alert has no extra context). Structure varies by dimension: most carry field-level changes with previousValue/currentValue pairs; AI Visibility carries a scoreShift with scoreFrom/scoreTo.
`createdAt`	`string`	When the alert was created (ISO-8601)

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

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

Alerts

List project alerts

Example

Fields