Skip to Content

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, ai-sources), severity (critical, high, medium, info), level (now, this_week, record), and competitor. Alerts are sorted by creation date (newest first). A pricing or positioning alert carries a level in the customer’s words: now is “Tell me now”, this_week is “Tell me this week”, record is “Keep a record”. Every level is listed here, records included; a record is stored and never delivered to any channel, and the app lists it only on its dimension’s page and under Records on the Alerts page. When a row on the page carries a level, a detail or a pricing or positioning context, the response opens with readingGuide, the rules for those fields.

Returns · { readingGuide, items, pagination }

Path parameters

NameTypeDescription
projectIdstringProject ID

Query parameters

NameTypeRequiredDescription
pagenumberPage number (1-indexed). Default 1. Min 1.
limitnumberNumber of items per page. Default 20. Range 1–100.
dimensionstringFilter by monitoring dimension (tech-trust, content, positioning, pricing, ai-visibility, ai-sources). Values: tech-trust, content, positioning, pricing, ai-visibility, ai-sources.
severitystringFilter by alert severity (critical, high, medium, info). Values: critical, high, medium, info.
levelstringFilter by level, on the pricing and positioning alerts that carry one: now is “Tell me now”, this_week is “Tell me this week”, record is “Keep a record” (stored, never sent on any channel). An alert of a dimension that writes no level never matches. Values: now, this_week, record.
competitorIdstringFilter by competitor ID

Request

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

Response 200 OK

{ "readingGuide": { "summary.pages": "Pages the engines RETRIEVED while answering, never pages they cited." }, "items": [ { "id": "507f1f77bcf86cd799439011", "dimension": "pricing", "competitorDomain": "rival-a.example", "competitorId": "507f1f77bcf86cd799439012", "severity": "medium", "level": "this_week", "title": "Rival A's free plan went from 5 monitors to 20 between 8 Mar and 10 May.", "detail": "Its check interval went from 3 minutes to 5; prices unchanged. Yours has 50 monitors at 5-minute checks.", "actionHint": "", "gapWarnings": [], "runId": "507f1f77bcf86cd799439013", "alertType": "value", "context": {}, "createdAt": "2026-03-15T10:00:00.000Z" } ], "pagination": { "page": 1, "limit": 20, "total": 47, "totalPages": 3, "hasMore": true } }

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

Errors

StatusCodeMeaning
401api_key_missing · api_key_invalid · api_key_revoked · api_key_expired · insufficient_scopeThe 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 } }
Last updated on