Skip to main content

​
Overview

All MentionLab REST API requests require an API key sent in the x-api-key header. Your API key is scoped to a single organization and can access all projects within that organization.
Project-scoped API keys are on the roadmap for Q2 2026.

​
Get Your API Key

You can retrieve your API key from the dashboard:
1

Sign in to MentionLab

Go to app.mentionlab.io and sign in to your account.
2

Open organization settings

Open your organization settings in the dashboard.
3

Generate API key

In the API section, click “Generate API Key” to create a new key.
4

Copy and store securely

Copy your API key immediately. For security reasons, you will not be able to see it again.
Your API key is only shown once when generated. Store it securely in a password manager or environment variable. If you lose it, you will need to generate a new one.

​
API Key Format

MentionLab API keys use the following format: 
ml_live_abc123xyz789def456...
API keys always start with ml_live_ for production keys.

​
Using Your API Key

Include your API key in the x-api-key header of every request: 
x-api-key: ml_live_abc123xyz789def456...

​
Example

curl -X GET "https://api.mentionlab.io/api/projects" \
  -H "x-api-key: ml_live_abc123xyz789..."

​
Environment Variables

We recommend storing your API key in environment variables: 
export MENTIONLAB_API_KEY="your-api-key-here"
Always add .env files to your .gitignore to prevent accidentally committing secrets to version control.

​
Required Headers

HeaderRequiredDescription
x-api-keyAlwaysYour API key (format: ml_live_...)
x-project-idFor project endpointsProject UUID for project-scoped operations

​
Example Request

curl -X GET "https://api.mentionlab.io/api/queries/list" \
  -H "x-api-key: ml_live_abc123xyz789..." \
  -H "x-project-id: fedcba98-7654-3210-fedc-ba9876543210" \
  -H "Content-Type: application/json"

​
Project Context

Project-specific endpoints require the x-project-id header so the API knows which project to operate on. You can store a default project ID in your environment if most requests target a single project.

​
Rate Limits

The MentionLab API implements rate limiting to ensure fair usage and maintain service stability for all users. Understanding these limits helps you design efficient integrations that avoid throttling.

​
Default Rate Limits

All accounts share the same default rate limits:
MetricLimit
Requests per Second10
Requests per Minute300
Requests per Hour10,000
If you have a custom agreement with MentionLab, your rate limits may differ from the defaults listed here. Please refer to your agreement documentation for your specific limits.

​
Rate Limit Headers

Every API response includes headers to help you track your usage:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the rate limit resets
Retry-AfterSeconds to wait before retrying (only on 429 responses)

​
Handling Rate Limits

When you exceed the rate limit, the API returns a 429 Too Many Requests response: 
{
  "statusCode": 429,
  "message": "Too many requests. Please retry after 30 seconds.",
  "error": "Too Many Requests"
}

​
Error Codes

CodeDescriptionAction
429Rate limit exceededWait for Retry-After seconds and retry
503Service temporarily unavailableWait 30 seconds and retry with backoff

​
Next Steps

Context Headers

See all header requirements and examples.

REST API Getting Started

Review base URL, JSON requirements, and rate limits.