API Overview
Welcome to the SerperMatrix API Reference. The SerperMatrix API provides high-performance, real-time search and web scraping services. All endpoints share a common base URL, header-based authentication, and structured JSON responses.
Base URL
All requests must be directed to the following base endpoint:
https://serpermatrix.com/api/v1
Authentication
Every API call requires an active API key to be sent in the request headers.
Pass your key using the X-API-KEY header:
X-API-KEY: sm_live_your_api_key_here
Keep your API keys confidential. Do not share them or hardcode them in front-end client code.
Custom Response Headers
Every API response returns custom headers containing real-time request metrics, latency telemetry, and billing usage tracking.
| Header Name | Type | Description |
|---|---|---|
X-Response-Time | string | The total execution time of the query in milliseconds (e.g., 124ms). |
X-Credits-Remaining | string | The remaining credit balance of your account. |
X-Cache | string | Status of our caching layer for this query. Returns HIT or MISS. |
X-RateLimit-Remaining | string | Number of requests remaining in your rate-limiting window (if throttled). |
HTTP Status Codes
We use conventional HTTP response status codes to indicate the success or failure of an API request.
| Status Code | Name | Description |
|---|---|---|
200 | OK | The request completed successfully and results are returned. |
400 | Bad Request | Invalid payload parameters or missing required fields. |
401 | Unauthorized | Missing, invalid, or expired X-API-KEY credentials. |
402 | Payment Required | Insufficient credits to perform the search or scrape request. |
429 | Too Many Requests | Rate or concurrency limits have been exceeded. |
OpenAPI Specification
You can download our official OpenAPI 3.0 specification files for automated SDK generation or API client import:
- JSON Format:
/api-reference/v1-openapi.json - YAML Format:
/api-reference/v1-openapi.yaml