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
/v1/projects/{projectId}/alertsGet 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.
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. | |
dimension | string | Filter by monitoring dimension (tech-trust, content, positioning, pricing, ai-visibility, ai-sources). Values: tech-trust, content, positioning, pricing, ai-visibility, ai-sources. | |
severity | string | Filter by alert severity (critical, high, medium, info). Values: critical, high, medium, info. | |
level | string | Filter 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. | |
competitorId | string | Filter 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
Example
{
"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
| 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
}
}