API Reference

API Documentation

Access your brand monitoring data programmatically. Available for Pro, Enterprise, and Pay-as-you-go plans.

Authentication

All API requests require an API key. Generate your key in your Profile page. Include it in the Authorization header:

Authorization: Bearer lbm_your_api_key_here

Keep your key secret. Do not share it or expose it in client-side code. If compromised, revoke it immediately in your Profile and generate a new one.

Base URL

https://llmbrandmonitor.com/api/v1

Rate Limits

The API allows 2 requests per second per API key. Every response includes rate limit headers:

Header	Description
X-RateLimit-Limit	Maximum requests per second (2)
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait (only on 429 responses)

Error Codes

All errors follow this format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid API key
FORBIDDEN	403	API key valid but access denied
NOT_FOUND	404	Resource not found
RATE_LIMITED	429	Too many requests
VALIDATION_ERROR	400	Invalid request parameters
INTERNAL_ERROR	500	Server error

Endpoints

GET

/api/v1/projects

Returns a paginated list of all your projects.

Query Parameters

Parameter	Type	Description
limit	number	Items per page (default: 20, max: 100)
offset	number	Number of items to skip (default: 0)
status	string	Filter by status: active, inactive, pending

Request Examples

curl -H "Authorization: Bearer lbm_your_key" \
  "https://llmbrandmonitor.com/api/v1/projects?limit=10"

Response Example

{
  "success": true,
  "data": [
    {
      "id": "proj_abc123",
      "projectName": "My Brand Monitor",
      "brandName": "Acme Corp",
      "domain": "acme.com",
      "language": "en",
      "location": "US",
      "visibilityPercent": 75.5,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "status": "active",
      "models": ["openai/gpt-4o", "anthropic/claude-sonnet-4-20250514"],
      "prompts": [{"text": "What companies provide..."}],
      "isArchived": false
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 10,
    "offset": 0,
    "hasMore": false
  }
}

GET

/api/v1/projects/:projectId

Returns detailed information about a single project.

Request Examples

curl -H "Authorization: Bearer lbm_your_key" \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123"

Response Example

{
  "success": true,
  "data": {
    "id": "proj_abc123",
    "projectName": "My Brand Monitor",
    "brandName": "Acme Corp",
    "domain": "acme.com",
    "language": "en",
    "location": "US",
    "visibilityPercent": 75.5,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "status": "active",
    "models": ["openai/gpt-4o", "anthropic/claude-sonnet-4-20250514"],
    "prompts": [{"text": "What companies provide..."}],
    "isArchived": false,
    "autoMonitoringConfig": {
      "enabled": true,
      "frequency": "daily",
      "nextRunAt": "2025-03-31T06:00:00.000Z",
      "lastStatus": "success"
    }
  }
}

GET

/api/v1/projects/:projectId/results

Returns monitoring results (summary data) for a project. Each result represents one prompt+model check.

Query Parameters

Parameter	Type	Description
limit	number	Items per page (default: 20, max: 100)
offset	number	Number of items to skip (default: 0)
status	string	Filter by status: success, failure, pending, queued

Request Examples

curl -H "Authorization: Bearer lbm_your_key" \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123/results?limit=50&status=success"

Response Example

{
  "success": true,
  "data": [
    {
      "id": "res_xyz789",
      "projectId": "proj_abc123",
      "promptText": "What are the best project management tools?",
      "modelId": "openai/gpt-4o",
      "modelName": "GPT-4o",
      "dateChecked": "2025-03-30T12:00:00.000Z",
      "status": "success",
      "brandMentioned": true,
      "detectedCompetitors": ["Competitor A", "Competitor B"],
      "extractedDomains": ["competitor-a.com"],
      "usedWebSearch": false
    }
  ],
  "pagination": {
    "total": 120,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

GET

/api/v1/projects/:projectId/competitors

Returns all detected competitors for a project, sorted by mention frequency.

Request Examples

curl -H "Authorization: Bearer lbm_your_key" \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123/competitors"

Response Example

{
  "success": true,
  "data": [
    {
      "id": "comp_001",
      "competitorName": "Competitor A",
      "firstSeen": "2025-02-01T00:00:00.000Z",
      "lastSeen": "2025-03-30T00:00:00.000Z",
      "mentionFrequency": 42,
      "visibilityPercent": 68.3
    },
    {
      "id": "comp_002",
      "competitorName": "Competitor B",
      "firstSeen": "2025-02-10T00:00:00.000Z",
      "lastSeen": "2025-03-29T00:00:00.000Z",
      "mentionFrequency": 28,
      "visibilityPercent": 45.1
    }
  ]
}

GET

/api/v1/projects/:projectId/history

Returns historical competitor mention statistics. Use preset time ranges or custom date ranges for advanced filtering.

Query Parameters

Parameter	Type	Description
timeRange	string	Preset range: 7d, 30d, or 90d (default: 30d)
startDate	string	Custom start date (YYYY-MM-DD). Overrides timeRange.
endDate	string	Custom end date (YYYY-MM-DD). Required with startDate.
modelFilter	string	Comma-separated model IDs to filter by
promptFilter	string	Comma-separated prompt texts to filter by

Request Examples

# Preset range
curl -H "Authorization: Bearer lbm_your_key" \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123/history?timeRange=30d"

# Custom date range with filters
curl -H "Authorization: Bearer lbm_your_key" \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123/history?startDate=2025-03-01&endDate=2025-03-30&modelFilter=openai/gpt-4o"

Response Example

{
  "success": true,
  "data": [
    {
      "competitorName": "Competitor A",
      "date": "2025-03-28T00:00:00.000Z",
      "mentionCount": 5
    },
    {
      "competitorName": "Competitor A",
      "date": "2025-03-29T00:00:00.000Z",
      "mentionCount": 3
    },
    {
      "competitorName": "Competitor B",
      "date": "2025-03-28T00:00:00.000Z",
      "mentionCount": 2
    }
  ]
}

Getting Started

Make sure you have a Pro, Enterprise, or Pay-as-you-go plan
Go to your Profile and generate an API key
Copy the key (it's shown only once)
Include it in the Authorization: Bearer header of your requests
Start querying your data using the endpoints above