Skip to content

Context7 Platform -- Up-to-date docs for AI agents

feat(metrics): add endpoint for retrieving library usage metrics (#2511)

Enes Gulesd4487448a391
diff --git a/docs/openapi.json b/docs/openapi.json
index d65a8ad3..c93a7c3a 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -99,6 +99,113 @@
]
}
},
+ "/v2/libs/metrics": {
+ "get": {
+ "summary": "Get library usage metrics",
+ "description": "Retrieve full usage metrics for a library: cumulative and daily request counters broken down by surface (web page, text docs, MCP, CLI), MCP client daily unique-user breakdown, and lifetime topic and country distributions. The API key's owning user must own the library — claim ownership at https://context7.com/add-library.",
+ "operationId": "getLibraryMetrics",
+ "tags": [
+ "Metrics"
+ ],
+ "parameters": [
+ {
+ "$ref": "#/components/parameters/LibraryIdParam"
+ },
+ {
+ "$ref": "#/components/parameters/DaysParam"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Library usage metrics",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/LibraryMetricsResponse"
+ },
+ "example": {
+ "total": {
+ "page": 12450,
+ "txt": 3820,
+ "mcp": 95210,
+ "cli": 1240
+ },
+ "daily": [
+ {
+ "date": "2025-01-14",
+ "page": 8,
+ "txt": 3,
+ "mcp": 42,
+ "cli": 1,
+ "total": 54
+ },
+ {
+ "date": "2025-01-15",
+ "page": 11,
+ "txt": 5,
+ "mcp": 67,
+ "cli": 0,
+ "total": 83
+ }
+ ],
+ "mcpClients": {
+ "dailyData": [
+ {
+ "date": "2025-01-14",
+ "uniqueUsersByClient": {
+ "cursor": 12,
+ "claude-code": 7
+ },
+ "totalUniqueUsers": 18
+ },
+ {
+ "date": "2025-01-15",
+ "uniqueUsersByClient": {
+ "cursor": 15,
+ "claude-code": 9,
+ "windsurf": 2
+ },
+ "totalUniqueUsers": 25
+ }
+ ]
+ },
+ "topics": [
+ { "topic": "routing", "count": 420 },
+ { "topic": "middleware", "count": 312 },
+ { "topic": "app-router", "count": 187 }
+ ],
+ "countries": [
+ { "country": "US", "count": 3120 },
+ { "country": "DE", "count": 842 },
+ { "country": "IN", "count": 610 }
+ ]
+ }
+ }
+ }
+ },
+ "400": {
+ "$ref": "#/components/responses/BadRequestError"
+ },
+ "401": {
+ "$ref": "#/components/responses/UnauthorizedError"
+ },
+ "403": {
+ "$ref": "#/components/responses/ForbiddenError"
+ },
+ "404": {
+ "$ref": "#/components/responses/NotFoundError"
+ },
+ "500": {
+ "$ref": "#/components/responses/InternalServerError"
+ }
+ },
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ]
+ }
+ },
"/v2/context": {
"get": {
"summary": "Get documentation context",
@@ -1407,6 +1514,19 @@
"default": "false"
},
"example": "true"
+ },
+ "DaysParam": {
+ "name": "days",
+ "in": "query",
+ "description": "Number of days of daily history to return (1-365). Defaults to 30.",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 365,
+ "default": 30
+ },
+ "example": 30
}
},
"schemas": {
@@ -1682,6 +1802,196 @@
"message"
]
},
+ "ProjectStats": {
+ "type": "object",
+ "description": "Cumulative request counts for a library, broken down by request surface",
+ "properties": {
+ "page": {
+ "type": "integer",
+ "description": "Requests served to the context7.com web UI"
+ },
+ "txt": {
+ "type": "integer",
+ "description": "Plain-text documentation requests"
+ },
+ "mcp": {
+ "type": "integer",
+ "description": "Requests served via the Context7 MCP server"
+ },
+ "cli": {
+ "type": "integer",
+ "description": "Requests served to the Context7 CLI"
+ }
+ },
+ "required": [
+ "page",
+ "txt",
+ "mcp",
+ "cli"
+ ]
+ },
+ "DailyStatsPoint": {
+ "type": "object",
+ "description": "Per-day request counts for a library (counts *on* this date, not cumulative)",
+ "properties": {
+ "date": {
+ "type": "string",
+ "format": "date",
+ "description": "UTC date in `YYYY-MM-DD` format",
+ "example": "2025-01-15"
+ },
+ "page": {
+ "type": "integer",
+ "description": "Requests served to the context7.com web UI on this date"
+ },
+ "txt": {
+ "type": "integer",
+ "description": "Plain-text documentation requests on this date"
+ },
+ "mcp": {
+ "type": "integer",
+ "description": "Requests served via the Context7 MCP server on this date"
+ },
+ "cli": {
+ "type": "integer",
+ "description": "Requests served to the Context7 CLI on this date"
+ },
+ "total": {
+ "type": "integer",
+ "description": "Sum of all request surfaces on this date (`page + txt + mcp + cli`)"
+ }
+ },
+ "required": [
+ "date",
+ "page",
+ "txt",
+ "mcp",
+ "cli",
+ "total"
+ ]
+ },
+ "LibraryMetricsResponse": {
+ "type": "object",
+ "description": "Library usage metrics response",
+ "properties": {
+ "total": {
+ "$ref": "#/components/schemas/ProjectStats"
+ },
+ "daily": {
+ "type": "array",
+ "description": "Per-day request counts (deltas, not cumulative), ordered from oldest to newest. Days with zero activity are omitted. Up to `days` points — fewer if the library has less history or had idle days in the window.",
+ "items": {
+ "$ref": "#/components/schemas/DailyStatsPoint"
+ }
+ },
+ "mcpClients": {
+ "$ref": "#/components/schemas/McpClientMetrics"
+ },
+ "topics": {
+ "type": "array",
+ "description": "Lifetime topic distribution, ordered by count descending",
+ "items": {
+ "$ref": "#/components/schemas/TopicCount"
+ }
+ },
+ "countries": {
+ "type": "array",
+ "description": "Lifetime country distribution (ISO-2 codes), ordered by count descending",
+ "items": {
+ "$ref": "#/components/schemas/CountryCount"
+ }
+ }
+ },
+ "required": [
+ "total",
+ "daily",
+ "mcpClients",
+ "topics",
+ "countries"
+ ]
+ },
+ "McpClientMetrics": {
+ "type": "object",
+ "description": "MCP client usage breakdown by day",
+ "properties": {
+ "dailyData": {
+ "type": "array",
+ "description": "Per-day MCP client unique-user breakdown, ordered from oldest to newest",
+ "items": {
+ "$ref": "#/components/schemas/McpDailyClientData"
+ }
+ }
+ },
+ "required": [
+ "dailyData"
+ ]
+ },
+ "McpDailyClientData": {
+ "type": "object",
+ "description": "Per-day MCP client unique users for a library",
+ "properties": {
+ "date": {
+ "type": "string",
+ "format": "date",
+ "description": "UTC date in `YYYY-MM-DD` format",
+ "example": "2025-01-15"
+ },
+ "uniqueUsersByClient": {
+ "type": "object",
+ "description": "Unique user count per MCP client identifier (e.g., `cursor`, `claude-code`, `windsurf`)",
+ "additionalProperties": {
+ "type": "integer"
+ }
+ },
+ "totalUniqueUsers": {
+ "type": "integer",
+ "description": "Total unique users across all clients for this library on this date"
+ }
+ },
+ "required": [
+ "date",
+ "uniqueUsersByClient",
+ "totalUniqueUsers"
+ ]
+ },
+ "TopicCount": {
+ "type": "object",
+ "description": "Topic with its lifetime request count",
+ "properties": {
+ "topic": {
+ "type": "string",
+ "description": "Normalized, lowercased topic string",
+ "example": "routing"
+ },
+ "count": {
+ "type": "integer",
+ "description": "Number of requests that referenced this topic"
+ }
+ },
+ "required": [
+ "topic",
+ "count"
+ ]
+ },
+ "CountryCount": {
+ "type": "object",
+ "description": "Country with its lifetime request count",
+ "properties": {
+ "country": {
+ "type": "string",
+ "description": "ISO 3166-1 alpha-2 country code",
+ "example": "US"
+ },
+ "count": {
+ "type": "integer",
+ "description": "Number of requests originating from this country"
+ }
+ },
+ "required": [
+ "country",
+ "count"
+ ]
+ },
"AddRepoRequest": {
"type": "object",
"description": "Request body for adding a Git repository",
@@ -2431,6 +2741,10 @@
{
"name": "Add Library",
"description": "Submit new libraries for documentation processing"
+ },
+ {
+ "name": "Metrics",
+ "description": "Retrieve usage metrics for libraries"
}
]
}