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/models

Returns a paginated list of available LLM models with pricing information. No authentication required.

Query Parameters

Parameter	Type	Description
limit	number	Items per page (default: 50, max: 500)
offset	number	Number of items to skip (default: 0)
available	boolean	If true, returns only models currently available. If false, returns empty list.
search	string	Case-insensitive substring match against model_id or name (e.g. gpt, claude).

Request Examples

curl "https://llmbrandmonitor.com/api/v1/models?limit=50&offset=0"

Response Example

{
  "success": true,
  "data": [
    {
      "model_id": "openai/gpt-4o",
      "name": "GPT-4o",
      "provider": "openai",
      "supports_web_search": false,
      "pricing": {
        "prompt": 2.5,
        "completion": 10
      }
    },
    {
      "model_id": "google/gemini-2.5-flash-preview",
      "name": "Gemini 2.5 Flash",
      "provider": "google",
      "supports_web_search": true,
      "pricing": {
        "prompt": 0.15,
        "completion": 0.6
      }
    }
  ],
  "pagination": {
    "total": 352,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

GET

/api/v1/usage

Returns credit usage statistics for the current billing period or a custom date range.

Query Parameters

Parameter	Type	Description
start_date	string	Period start in ISO 8601 format (e.g. 2026-04-01T00:00:00.000Z)
end_date	string	Period end in ISO 8601 format. Required if start_date is set

Request Examples

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

# With custom date range:
curl -H "Authorization: Bearer lbm_your_key" \
  "https://llmbrandmonitor.com/api/v1/usage?start_date=2026-04-01T00:00:00.000Z&end_date=2026-04-15T23:59:59.999Z"

Response Example

{
  "success": true,
  "data": {
    "checks_used": 318,
    "checks_limit": 500,
    "checks_remaining": 182,
    "plan": "pro",
    "period": {
      "start": "2026-04-01T00:00:00.000Z",
      "end": "2026-04-30T23:59:59.999Z"
    }
  }
}

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": [
    {
      "project_id": "proj_abc123",
      "project_name": "My Brand Monitor",
      "brand_name": "Acme Corp",
      "domain": "acme.com",
      "language": "en",
      "location": "United States",
      "visibility_percent": 75.5,
      "created_at": "2025-01-15T10:30:00.000Z",
      "status": "active",
      "models": ["openai/gpt-4o", "anthropic/claude-sonnet-4-20250514"],
      "prompts": [{"prompt_id": "prm_a1b2", "text": "What companies provide..."}],
      "is_archived": false
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 10,
    "offset": 0,
    "has_more": false
  }
}

POST

/api/v1/projects

Create a new monitoring project with brand name, prompts, and model selection. Use `language` as a 2-letter ISO code (e.g. `en`, `de`) and `location` as either a full country name (e.g. `United States`, `Ukraine`), a 2-letter ISO 3166-1 alpha-2 code (e.g. `US`, `UA`), or `auto` for auto-detect.

Request Examples

curl -X POST \
  -H "Authorization: Bearer lbm_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "Nike Brand Monitor",
    "brand_name": "Nike",
    "domain": "nike.com",
    "language": "en",
    "location": "auto",
    "models": ["openai/gpt-4o", "anthropic/claude-sonnet-4-20250514"],
    "prompts": [
      { "text": "What are the best running shoes?", "tags": ["non-branded"] },
      { "text": "Tell me about Nike running shoes", "tags": ["branded"] }
    ],
    "auto_monitoring": { "enabled": false }
  }' \
  "https://llmbrandmonitor.com/api/v1/projects"

Response Example

{
  "success": true,
  "data": {
    "project_id": "proj_abc123",
    "project_name": "Nike Brand Monitor",
    "brand_name": "Nike",
    "domain": "nike.com",
    "language": "en",
    "location": "auto",
    "visibility_percent": 0,
    "created_at": "2026-04-09T12:00:00.000Z",
    "status": "active",
    "models": ["openai/gpt-4o"],
    "prompts": [
      { "prompt_id": "prm_a1b2", "text": "What are the best running shoes?", "tags": [] }
    ],
    "is_archived": false,
    "auto_monitoring_config": { "enabled": false, "frequency": "daily" }
  }
}

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": {
    "project_id": "proj_abc123",
    "project_name": "My Brand Monitor",
    "brand_name": "Acme Corp",
    "domain": "acme.com",
    "language": "en",
    "location": "United States",
    "visibility_percent": 75.5,
    "created_at": "2025-01-15T10:30:00.000Z",
    "status": "active",
    "models": ["openai/gpt-4o", "anthropic/claude-sonnet-4-20250514"],
    "prompts": [{"prompt_id": "prm_a1b2", "text": "What companies provide..."}],
    "is_archived": false,
    "auto_monitoring_config": {
      "enabled": true,
      "frequency": "daily",
      "next_run_at": "2025-03-31T06:00:00.000Z",
      "last_status": "success"
    }
  }
}

PATCH

/api/v1/projects/:projectId

Partially update a project. Only provided fields are changed. Cannot modify brand_name or prompts (use dedicated endpoints for prompts).

Request Examples

curl -X PATCH \
  -H "Authorization: Bearer lbm_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "project_name": "Updated Name", "models": ["openai/gpt-4o"] }' \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123"

# Update auto-monitoring
curl -X PATCH \
  -H "Authorization: Bearer lbm_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "auto_monitoring": { "enabled": true, "frequency": "weekly" } }' \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123"

Response Example

{
  "success": true,
  "data": {
    "project_id": "proj_abc123",
    "project_name": "Updated Name",
    "brand_name": "Acme Corp",
    "status": "active",
    "models": ["openai/gpt-4o", "google/gemini-pro"],
    "is_archived": false,
    "auto_monitoring_config": {
      "enabled": true,
      "frequency": "weekly",
      "next_run_at": "2026-04-16T06:00:00.000Z",
      "last_status": "queued"
    }
  }
}

DELETE

/api/v1/projects/:projectId

Archive or permanently delete a project. Default mode is archive (reversible). Permanent deletion requires a confirmation header.

Query Parameters

Parameter	Type	Description
mode	string	"archive" (default) or "delete" (permanent, irreversible)

Request Examples

# Archive a project (default)
curl -X DELETE -H "Authorization: Bearer lbm_your_key" \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123"

# Permanently delete (requires confirmation header)
curl -X DELETE -H "Authorization: Bearer lbm_your_key" \
  -H "X-Confirm-Delete: true" \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123?mode=delete"

Response Example

{
  "success": true,
  "data": {
    "mode": "archive"
  }
}

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
tags	string	Comma-separated tags to filter by (OR logic). Only results for prompts with matching tags are returned.
scan_id	string	Filter results by scan ID

Request Examples

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

# Filter by tags (non-brand prompts only)
curl -H "Authorization: Bearer lbm_your_key" \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123/results?tags=non-brand"

# Filter by scan ID
curl -H "Authorization: Bearer lbm_your_key" \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123/results?scan_id=scan_abc123"

Response Example

{
  "success": true,
  "data": [
    {
      "result_id": "res_xyz789",
      "project_id": "proj_abc123",
      "prompt_text": "What are the best project management tools?",
      "model_id": "openai/gpt-4o",
      "model_name": "GPT-4o",
      "date_checked": "2025-03-30T12:00:00.000Z",
      "status": "success",
      "brand_mentioned": true,
      "detected_competitors": ["Competitor A", "Competitor B"],
      "extracted_domains": ["competitor-a.com"],
      "used_web_search": false,
      "scan_id": "scan_abc123",
      "prompt_tags": ["enterprise", "non-brand"]
    }
  ],
  "pagination": {
    "total": 120,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

GET

/api/v1/projects/:projectId/results/:resultId/transcript

Returns the full LLM response transcript for a specific monitoring result, including extracted links and token usage.

Request Examples

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

Response Example

{
  "success": true,
  "data": {
    "result_id": "res_xyz789",
    "project_id": "proj_abc123",
    "prompt_text": "What are the best project management tools?",
    "model_id": "openai/gpt-4o",
    "model_name": "GPT-4o",
    "date_checked": "2026-03-30T12:00:00.000Z",
    "status": "success",
    "transcript": "Here are some of the best project management tools...",
    "brand_mentioned": true,
    "detected_competitors": ["Asana", "Monday.com"],
    "extracted_domains": ["asana.com", "monday.com"],
    "extracted_links": ["https://asana.com/product", "https://monday.com"],
    "used_web_search": false,
    "token_usage": { "prompt": 120, "completion": 480 }
  }
}

GET

/api/v1/projects/:projectId/competitors

Returns a paginated list of detected competitors for a project, sorted by mention frequency. When tags filter is applied, competitors are recalculated from matching results only.

Query Parameters

Parameter	Type	Description
limit	number	Items per page (default: 20, max: 100)
offset	number	Number of items to skip (default: 0)
tags	string	Comma-separated tags to filter by. Competitor stats are recalculated from results matching these tags.

Request Examples

# All competitors (paginated)
curl -H "Authorization: Bearer lbm_your_key" \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123/competitors?limit=50"

# Non-brand segment only
curl -H "Authorization: Bearer lbm_your_key" \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123/competitors?tags=non-brand&limit=50"

Response Example

{
  "success": true,
  "data": [
    {
      "competitor_id": "comp_001",
      "competitor_name": "Competitor A",
      "first_seen": "2025-02-01T00:00:00.000Z",
      "last_seen": "2025-03-30T00:00:00.000Z",
      "mention_frequency": 42,
      "visibility_percent": 68.3
    },
    {
      "competitor_id": "comp_002",
      "competitor_name": "Competitor B",
      "first_seen": "2025-02-10T00:00:00.000Z",
      "last_seen": "2025-03-29T00:00:00.000Z",
      "mention_frequency": 28,
      "visibility_percent": 45.1
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

GET

/api/v1/projects/:projectId/history

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

Query Parameters

Parameter	Type	Description
limit	number	Items per page (default: 50, max: 200)
offset	number	Number of items to skip (default: 0)
time_range	string	Preset range: 7d, 30d, or 90d (default: 30d)
start_date	string	Custom start date (YYYY-MM-DD). Overrides time_range.
end_date	string	Custom end date (YYYY-MM-DD). Required with start_date.
model_filter	string	Comma-separated model IDs to filter by
prompt_filter	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?time_range=30d&limit=100"

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

Response Example

{
  "success": true,
  "data": [
    {
      "competitor_name": "Competitor A",
      "date_stats": [
        { "date": "2025-03-29", "mention_count": 3 },
        { "date": "2025-03-28", "mention_count": 5 }
      ]
    },
    {
      "competitor_name": "Competitor B",
      "date_stats": [
        { "date": "2025-03-28", "mention_count": 2 }
      ]
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

POST

/api/v1/projects/:projectId/prompts

Add one or more prompts to a project. Maximum 50 prompts per request, 100 per project total.

Request Examples

curl -X POST \
  -H "Authorization: Bearer lbm_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": [
      { "text": "Is ProductX recommended for enterprise use?", "tags": ["enterprise"] },
      { "text": "Compare ProductX with competitors" }
    ]
  }' \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123/prompts"

Response Example

{
  "success": true,
  "data": [
    {
      "prompt_id": "prm_aBcD1234efgh",
      "text": "Is ProductX recommended for enterprise use?",
      "tags": ["enterprise"],
      "created_at": "2026-04-09T12:00:00.000Z"
    },
    {
      "prompt_id": "prm_xYz5678ijkl",
      "text": "Compare ProductX with competitors",
      "tags": [],
      "created_at": "2026-04-09T12:00:00.000Z"
    }
  ]
}

DELETE

/api/v1/projects/:projectId/prompts/:promptId

Deletes a prompt from the project by its prompt_id (e.g. prm_xxx). The project must have at least 2 prompts and must not be archived.

Request Examples

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

Response Example

{
  "success": true
}

GET

/api/v1/projects/:projectId/links

Returns aggregated link and domain statistics extracted from monitoring results.

Query Parameters

Parameter	Type	Description
limit	number	Items per page (default: 20, max: 100)
offset	number	Number of items to skip (default: 0)
domain	string	Filter by exact domain name
min_frequency	number	Minimum number of results mentioning the domain
tags	string	Comma-separated prompt tags to filter by

Request Examples

curl -H "Authorization: Bearer lbm_your_key" \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123/links?min_frequency=5"

Response Example

{
  "success": true,
  "data": [
    {
      "domain": "asana.com",
      "frequency": 15,
      "unique_urls": 4,
      "urls": [
        { "url": "https://asana.com/product", "mention_count": 8 },
        { "url": "https://asana.com/blog/review", "mention_count": 7 }
      ]
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

GET

/api/v1/projects/:projectId/scans

Returns a paginated list of scans for a project, sorted by creation date (newest first).

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: queued, running, completed, partial, failed

Request Examples

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

# Filter by status
curl -H "Authorization: Bearer lbm_your_key" \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123/scans?status=completed"

Response Example

{
  "success": true,
  "data": [
    {
      "scan_id": "scan_xyz789",
      "status": "completed",
      "total_checks": 18,
      "completed_checks": 18,
      "successful_checks": 18,
      "failed_checks": 0,
      "credits_used": 18,
      "trigger_source": "api",
      "created_at": "2026-04-09T10:00:00.000Z",
      "started_at": "2026-04-09T10:00:05.000Z",
      "completed_at": "2026-04-09T10:02:30.000Z"
    },
    {
      "scan_id": "scan_abc456",
      "status": "running",
      "total_checks": 10,
      "completed_checks": 5,
      "successful_checks": 5,
      "failed_checks": 0,
      "credits_used": 5,
      "trigger_source": "ui",
      "created_at": "2026-04-09T11:00:00.000Z",
      "started_at": "2026-04-09T11:00:05.000Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 10,
    "offset": 0,
    "has_more": false
  }
}

GET

/api/v1/projects/:projectId/scans/:scanId

Returns the status and details of a specific scan. Use for polling scan progress after starting a scan.

Request Examples

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

Response Example

{
  "success": true,
  "data": {
    "scan_id": "scan_xyz789",
    "project_id": "proj_abc123",
    "status": "completed",
    "total_checks": 18,
    "completed_checks": 18,
    "successful_checks": 16,
    "failed_checks": 2,
    "credits_used": 18,
    "trigger_source": "api",
    "created_at": "2026-04-09T10:00:00.000Z",
    "started_at": "2026-04-09T10:00:05.000Z",
    "completed_at": "2026-04-09T10:02:30.000Z"
  }
}

POST

/api/v1/projects/:projectId/scans

Start a new scan for a project. All fields are optional — defaults to all prompts × all models. Returns 202 for new scans, 200 if an identical scan is already running.

Request Examples

# Scan all prompts with all models
curl -X POST \
  -H "Authorization: Bearer lbm_your_key" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123/scans"

# Scan specific prompts and models
curl -X POST \
  -H "Authorization: Bearer lbm_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "prompt_ids": ["prm_a1b2"], "models": ["openai/gpt-4o"], "use_web_search": true }' \
  "https://llmbrandmonitor.com/api/v1/projects/proj_abc123/scans"

Response Example

{
  "success": true,
  "data": {
    "scan_id": "scan_xyz789",
    "project_id": "proj_abc123",
    "status": "queued",
    "total_checks": 18,
    "credits_used": 18,
    "credits_remaining": 182,
    "created_at": "2026-04-09T10:00:00.000Z"
  }
}

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