> ## Documentation Index
> Fetch the complete documentation index at: https://leadmagic.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics API

> Monitor your API usage with comprehensive analytics endpoints

# Usage Analytics

Get detailed insights into your API usage, credit consumption, and performance metrics. All analytics endpoints are **free** and don't consume credits.

> [!NOTE]
>
> **100% Free:** All analytics endpoints consume zero credits and have no rate limits. Use them to build dashboards, monitoring systems, and usage alerts.

## Quick Reference

| Endpoint | Method | Description | Best For |
| - | - | - | - |
| `/v1/analytics/dashboard` | GET | Real-time account status | Live dashboards, health checks |
| `/v1/analytics/usage` | GET | Daily usage summary | Weekly/monthly reports |
| `/v1/analytics/products` | GET | Per-product breakdown | Cost optimization |
| `/v1/analytics/credits` | GET | Credit consumption history | Spend tracking |
| `/v1/analytics/summary` | GET | All-time statistics | Account overview |
| `/v1/analytics/daily` | GET | Daily performance metrics | SLA monitoring |
| `/v1/analytics/day/:date` | GET | Single day breakdown | Debugging, audits |

***

## Dashboard

Get a real-time snapshot of your account status including credits, rate limits, and usage statistics.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/dashboard
```

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.leadmagic.io/v1/analytics/dashboard' \
  -H 'X-API-Key: YOUR_API_KEY'
```

```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch('https://api.leadmagic.io/v1/analytics/dashboard', {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const dashboard = await response.json();
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests

response = requests.get(
    'https://api.leadmagic.io/v1/analytics/dashboard',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
dashboard = response.json()
```

```go Go theme={"theme":{"light":"github-light","dark":"github-dark"}}
req, _ := http.NewRequest("GET", "https://api.leadmagic.io/v1/analytics/dashboard", nil)
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
```

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "user": {
    "id": "user_abc123",
    "email": "developer@leadmagic.io"
  },
  "credits": {
    "current": 15432.50,
    "formatted": "$154.33"
  },
  "rate_limit": {
    "minute": {
      "limit": 300,
      "used": 45,
      "remaining": 255,
      "utilization": 15.0
    },
    "daily": {
      "limit": 500000,
      "used": 12500,
      "remaining": 487500,
      "utilization": 2.5
    }
  },
  "concurrency": {
    "current": 0,
    "peak": 23,
    "active_reservations": 0
  },
  "stats": {
    "today": {
      "requests": 1250,
      "credits": 875.50,
      "chargeable_requests": 1100,
      "chargeable_rate": 88.0,
      "unique_products": 5
    },
    "this_week": {
      "requests": 8500,
      "credits": 5200.25,
      "chargeable_requests": 7200,
      "chargeable_rate": 84.7,
      "unique_products": 8
    },
    "this_month": {
      "requests": 45000,
      "credits": 28500.00,
      "chargeable_requests": 38000,
      "chargeable_rate": 84.4,
      "unique_products": 12
    }
  }
}
```

### Response Fields

**user** `object` *required*

Your account information

**properties**

**id** `string`

Unique user identifier

**email** `string`

Account email address

**credits** `object` *required*

Current credit balance

**properties**

**current** `number`

Raw credit balance (1 credit = \$0.01)

**formatted** `string`

Human-readable dollar value

**rate\_limit** `object` *required*

Real-time rate limit status

**properties**

**minute.limit** `number`

Requests per minute allowed

**minute.used** `number`

Requests used this minute

**minute.remaining** `number`

Requests remaining this minute

**minute.utilization** `number`

Percentage of limit used (0-100)

**daily.limit** `number`

Requests per day allowed

**daily.used** `number`

Requests used today

**daily.remaining** `number`

Requests remaining today

**daily.utilization** `number`

Percentage of daily limit used

**concurrency** `object` *required*

Concurrent request tracking

**properties**

**current** `number`

Currently in-flight requests

**peak** `number`

Peak concurrent requests (session)

**active\_reservations** `number`

Credit reservations pending

**stats** `object` *required*

Usage statistics for today, this week, and this month

**properties**

**requests** `number`

Total API requests

**credits** `number`

Total credits consumed

**chargeable\_requests** `number`

Requests that consumed credits

**chargeable\_rate** `number`

Percentage of requests charged

**unique\_products** `number`

Number of different endpoints used

***

## Usage Summary

Get aggregated usage metrics over a time period with daily breakdown.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/usage?days=30
```

**days** `number` (default: 30)

Number of days to include (1-90)

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "period": {
    "start": "2026-10-02",
    "end": "2026-11-01",
    "days": 30
  },
  "summary": {
    "total_requests": 45000,
    "chargeable_requests": 38000,
    "total_credits": 28500.00,
    "avg_credits_per_request": 0.63,
    "chargeable_rate": 84.4,
    "unique_products": 12
  },
  "daily": [
    {
      "date": "2026-11-01",
      "total_requests": 1250,
      "chargeable_requests": 1100,
      "total_credits": 875.50,
      "unique_products_used": 5
    }
  ]
}
```

> [!TIP]
>
> **Chargeable Rate** shows what percentage of your requests consumed credits. A lower rate means more free results (unknown validations, not-found responses, etc.).

***

## Products Breakdown

Get per-product usage with requests, credits, and success rates. Essential for cost optimization.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/products?days=30
```

**days** `number` (default: 30)

Number of days to include (1-90)

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "period": {
    "start": "2026-10-02",
    "end": "2026-11-01",
    "days": 30
  },
  "products": {
    "email_validation": {
      "total_requests": 20000,
      "total_credits": 5000.00,
      "successful_requests": 19500,
      "failed_requests": 500,
      "success_rate": 97.5,
      "avg_credits_per_request": 0.25
    },
    "email_finder": {
      "total_requests": 10000,
      "total_credits": 8500.00,
      "successful_requests": 8500,
      "failed_requests": 1500,
      "success_rate": 85.0,
      "avg_credits_per_request": 0.85
    }
  },
  "daily": [...]
}
```

> [!WARNING]
>
> **Success rate** means we found data. For email finder, 85% success means 85% of lookups returned an email. You only pay for successful results.

***

## Credit History

Get credit consumption history with daily breakdown. Perfect for spend tracking and budgeting.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/credits?days=30
```

**days** `number` (default: 30)

Number of days to include (1-90)

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "period": {
    "start": "2026-10-02",
    "end": "2026-11-01",
    "days": 30
  },
  "summary": {
    "total_credits": 28500.00,
    "total_requests": 45000,
    "chargeable_requests": 38000,
    "avg_credits_per_request": 0.63,
    "chargeable_rate": 84.4
  },
  "daily": [
    {
      "date": "2026-11-01",
      "total_credits": 875.50,
      "total_requests": 1250,
      "chargeable_requests": 1100
    }
  ]
}
```

***

## All-Time Summary

Get lifetime statistics for your account, or specify a custom date range.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/summary
GET /v1/analytics/summary?start_date=2026-10-01&end_date=2026-11-01
```

**start\_date** `string`

Start date (YYYY-MM-DD format). Optional.

**end\_date** `string`

End date (YYYY-MM-DD format). Optional.

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "total_api_requests": 1250000,
  "total_credits_consumed": 425000.50,
  "unique_products_used": 15,
  "successful_requests": 1150000,
  "failed_requests": 100000,
  "success_rate": 92.0,
  "avg_response_time_ms": 245,
  "first_request": "2023-06-15T10:30:00.000Z",
  "last_request": "2026-11-01T14:22:00.000Z"
}
```

***

## Daily Metrics

Get detailed daily metrics including latency percentiles and error rates. Essential for SLA monitoring.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/daily?days=30
```

**days** `number` (default: 30)

Number of days to include (1-90)

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "period": {
    "start": "2026-10-02",
    "end": "2026-11-01",
    "days": 30
  },
  "data": [
    {
      "date": "2026-11-01",
      "total_requests": 1250,
      "successful_requests": 1175,
      "failed_requests": 75,
      "total_credits": 875.50,
      "p50_latency_ms": 180,
      "p95_latency_ms": 450,
      "p99_latency_ms": 890,
      "error_rate": 6.0
    }
  ]
}
```

### Latency Percentiles

| Metric | Description |
| - | - |
| `p50_latency_ms` | Median response time (50th percentile) |
| `p95_latency_ms` | 95% of requests faster than this |
| `p99_latency_ms` | 99% of requests faster than this |

***

## Day Breakdown

Get per-product breakdown for a specific day. Perfect for debugging and audits.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/day/2026-11-01
```

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "date": "2026-11-01",
  "summary": {
    "total_credits": 875.50,
    "total_requests": 1250,
    "products_count": 8
  },
  "products": [
    {
      "product_id": "email_validation",
      "requests": 500,
      "credits": 125.00,
      "credits_percentage": 14.29,
      "avg_credits_per_request": 0.25,
      "max_credits": 0.25
    },
    {
      "product_id": "email_finder",
      "requests": 350,
      "credits": 297.50,
      "credits_percentage": 34.00,
      "avg_credits_per_request": 0.85,
      "max_credits": 1.00
    }
  ]
}
```

***

## Practical Examples

> [tab] Monitoring Dashboard
>
> ### Build a Real-Time Dashboard
>
> Fetch all metrics in parallel for a comprehensive dashboard:
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const headers = { 'X-API-Key': process.env.LEADMAGIC_API_KEY };
>
> async function getDashboardMetrics() {
>   const [dashboard, usage, products, daily] = await Promise.all([
>     fetch('https://api.leadmagic.io/v1/analytics/dashboard', { headers }),
>     fetch('https://api.leadmagic.io/v1/analytics/usage?days=7', { headers }),
>     fetch('https://api.leadmagic.io/v1/analytics/products?days=7', { headers }),
>     fetch('https://api.leadmagic.io/v1/analytics/daily?days=7', { headers })
>   ]).then(responses => Promise.all(responses.map(r => r.json())));
>
>   return {
>     // Account health
>     credits: dashboard.data.credits.current,
>     creditsFormatted: dashboard.data.credits.formatted,
>
>     // Rate limits
>     minuteUtilization: dashboard.data.rate_limit.minute.utilization,
>     dailyUtilization: dashboard.data.rate_limit.daily.utilization,
>
>     // Weekly stats
>     weeklyRequests: usage.data.summary.total_requests,
>     weeklyCredits: usage.data.summary.total_credits,
>     chargeableRate: usage.data.summary.chargeable_rate,
>
>     // Top products by spend
>     topProducts: Object.entries(products.data.products)
>       .sort((a, b) => b[1].total_credits - a[1].total_credits)
>       .slice(0, 5),
>
>     // Performance
>     avgLatency: daily.data.data.reduce((sum, d) => sum + d.p50_latency_ms, 0) / daily.data.data.length,
>     avgErrorRate: daily.data.data.reduce((sum, d) => sum + d.error_rate, 0) / daily.data.data.length
>   };
> }
> ```

> [tab] Alerting
>
> ### Set Up Usage Alerts
>
> Monitor credits and rate limits to prevent service interruptions:
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> async function checkAndAlert() {
>   const response = await fetch('https://api.leadmagic.io/v1/analytics/dashboard', {
>     headers: { 'X-API-Key': process.env.LEADMAGIC_API_KEY }
>   });
>   const { data } = await response.json();
>
>   const alerts = [];
>
>   // Credit alerts
>   if (data.credits.current < 100) {
>     alerts.push({
>       level: 'critical',
>       message: `Credits critically low: ${data.credits.formatted}`
>     });
>   } else if (data.credits.current < 1000) {
>     alerts.push({
>       level: 'warning', 
>       message: `Credits running low: ${data.credits.formatted}`
>     });
>   }
>
>   // Rate limit alerts
>   if (data.rate_limit.daily.utilization > 90) {
>     alerts.push({
>       level: 'warning',
>       message: `Daily rate limit at ${data.rate_limit.daily.utilization}%`
>     });
>   }
>
>   if (data.rate_limit.minute.utilization > 80) {
>     alerts.push({
>       level: 'warning',
>       message: `Minute rate limit at ${data.rate_limit.minute.utilization}%`
>     });
>   }
>
>   // Send alerts via Slack, email, PagerDuty, etc.
>   for (const alert of alerts) {
>     await sendAlert(alert);
>   }
>
>   return alerts;
> }
>
> // Run every 5 minutes
> setInterval(checkAndAlert, 5 * 60 * 1000);
> ```

> [tab] Cost Optimization
>
> ### Analyze and Optimize Spending
>
> Identify which products consume the most credits:
>
> ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
> import requests
>
> def analyze_spending():
>     headers = {'X-API-Key': 'YOUR_API_KEY'}
>
>     # Get last 30 days of product usage
>     response = requests.get(
>         'https://api.leadmagic.io/v1/analytics/products?days=30',
>         headers=headers
>     )
>     data = response.json()['data']
>
>     # Calculate cost breakdown
>     products = data['products']
>     total_credits = sum(p['total_credits'] for p in products.values())
>
>     print(f"Total spend: ${total_credits * 0.01:.2f}")
>     print("\nBreakdown by product:")
>
>     for product_id, stats in sorted(
>         products.items(), 
>         key=lambda x: x[1]['total_credits'], 
>         reverse=True
>     ):
>         percentage = (stats['total_credits'] / total_credits) * 100
>         cost = stats['total_credits'] * 0.01
>
>         print(f"  {product_id}:")
>         print(f"    Requests: {stats['total_requests']:,}")
>         print(f"    Credits: {stats['total_credits']:,.2f} ({percentage:.1f}%)")
>         print(f"    Cost: ${cost:.2f}")
>         print(f"    Success rate: {stats['success_rate']}%")
>         print(f"    Avg per request: {stats['avg_credits_per_request']:.3f}")
>         print()
> ```

> [tab] SLA Monitoring
>
> ### Track Performance SLAs
>
> Monitor latency and error rates against your SLA targets:
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const SLA_TARGETS = {
>   p95_latency_ms: 1000,  // 1 second
>   p99_latency_ms: 2000,  // 2 seconds
>   error_rate: 5.0        // 5%
> };
>
> async function checkSLA() {
>   const response = await fetch(
>     'https://api.leadmagic.io/v1/analytics/daily?days=7',
>     { headers: { 'X-API-Key': process.env.LEADMAGIC_API_KEY } }
>   );
>   const { data } = await response.json();
>
>   const violations = [];
>
>   for (const day of data.data) {
>     if (day.p95_latency_ms > SLA_TARGETS.p95_latency_ms) {
>       violations.push({
>         date: day.date,
>         metric: 'p95_latency',
>         value: day.p95_latency_ms,
>         target: SLA_TARGETS.p95_latency_ms
>       });
>     }
>
>     if (day.error_rate > SLA_TARGETS.error_rate) {
>       violations.push({
>         date: day.date,
>         metric: 'error_rate',
>         value: day.error_rate,
>         target: SLA_TARGETS.error_rate
>       });
>     }
>   }
>
>   return {
>     period: data.period,
>     violations,
>     slaCompliant: violations.length === 0
>   };
> }
> ```

***

## Best Practices

> [accordion] Cache dashboard responses
>
> Analytics endpoints are free, but caching improves your dashboard performance:
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> let cache = { data: null, timestamp: 0 };
> const CACHE_TTL = 60 * 1000; // 1 minute
>
> async function getCachedDashboard() {
>   if (cache.data && Date.now() - cache.timestamp < CACHE_TTL) {
>     return cache.data;
>   }
>
>   const response = await fetch('https://api.leadmagic.io/v1/analytics/dashboard', {
>     headers: { 'X-API-Key': process.env.LEADMAGIC_API_KEY }
>   });
>
>   cache = { data: await response.json(), timestamp: Date.now() };
>   return cache.data;
> }
> ```

> [accordion] Use response headers instead
>
> Every API response includes `X-Credits-Remaining` — use this instead of polling the dashboard:
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const response = await fetch('https://api.leadmagic.io/v1/people/email-validation', {
>   method: 'POST',
>   headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
>   body: JSON.stringify({ email: 'test@example.com' })
> });
>
> const creditsRemaining = response.headers.get('X-Credits-Remaining');
> const requestId = response.headers.get('X-Request-Id');
>
> console.log(`Credits after request: ${creditsRemaining}`);
> ```

> [accordion] Batch analytics calls
>
> Fetch multiple analytics endpoints in parallel:
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const [dashboard, products, daily] = await Promise.all([
>   fetch('/v1/analytics/dashboard', { headers }),
>   fetch('/v1/analytics/products?days=30', { headers }),
>   fetch('/v1/analytics/daily?days=30', { headers })
> ]).then(responses => Promise.all(responses.map(r => r.json())));
> ```

> [accordion] Set up regular reporting
>
> Schedule weekly reports using cron or serverless functions:
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> // Weekly summary report
> async function generateWeeklyReport() {
>   const [usage, products] = await Promise.all([
>     fetch('/v1/analytics/usage?days=7', { headers }).then(r => r.json()),
>     fetch('/v1/analytics/products?days=7', { headers }).then(r => r.json())
>   ]);
>
>   return {
>     period: usage.data.period,
>     totalRequests: usage.data.summary.total_requests,
>     totalCredits: usage.data.summary.total_credits,
>     topProducts: Object.entries(products.data.products)
>       .sort((a, b) => b[1].total_credits - a[1].total_credits)
>       .slice(0, 5)
>       .map(([id, stats]) => ({ id, ...stats }))
>   };
> }
> ```

***

## Related

> [card] [Check Credits](https://leadmagic.io/docs/v1/reference/check-credits.md)
>
> Simple endpoint to check your current balance.

> [card] [Rate Limits](https://leadmagic.io/docs/v1/making-api-calls.md#rate-limits)
>
> Learn about rate limiting and how to stay within limits.


## OpenAPI

````yaml get /v1/analytics/dashboard
openapi: 3.1.0
info:
  title: LeadMagic API
  version: 1.4.34
  description: >
    # LeadMagic API Documentation


    The LeadMagic API provides comprehensive B2B data enrichment services
    including email validation, email finding, profile search, company
    intelligence, and more.


    ## Quick Start


    1. Get your API key from the [LeadMagic Dashboard](https://app.leadmagic.io)

    2. Add the `X-API-Key` header to all requests

    3. Start enriching your data!


    ## Base URL


    All API requests should be made to: `https://api.leadmagic.io`


    ## Rate Limits


    Each endpoint has specific rate limits (requests per minute). Exceeding
    limits returns a `429 Too Many Requests` response.


    ## Credits


    API calls consume credits based on the endpoint used. Check your balance
    with the `/v1/credits` endpoint.


    ## Support


    Contact us at support@leadmagic.io for assistance.
  contact:
    name: LeadMagic Support
    email: support@leadmagic.io
    url: https://leadmagic.io
  termsOfService: https://leadmagic.io/legal/terms
servers:
  - url: https://api.leadmagic.io
    description: Production API Server
security:
  - ApiKeyAuth: []
tags:
  - name: Credits
    description: Manage and check your credit balance
  - name: Analytics
    description: >-
      Monitor your API usage with comprehensive analytics endpoints (FREE - no
      credits consumed)
  - name: People Enrichment
    description: Find and validate contact information for individuals
  - name: Company Data
    description: Discover company information and intelligence
  - name: Jobs Data
    description: Search job listings and detect career changes
  - name: Ads Data
    description: Search advertising data across platforms
paths:
  /v1/analytics/dashboard:
    get:
      tags:
        - Analytics
      summary: Dashboard Overview
      description: >-
        Get a real-time snapshot of your account including credits, rate limits,
        and usage statistics.
      operationId: analytics-dashboard
      responses:
        '200':
          description: Dashboard data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    properties:
                      id:
                        type: string
                        example: user_abc123
                      email:
                        type: string
                        example: developer@leadmagic.io
                  credits:
                    type: object
                    properties:
                      current:
                        type: number
                        example: 15432.5
                      formatted:
                        type: string
                        example: $154.33
                  rate_limit:
                    type: object
                    properties:
                      minute:
                        type: object
                        properties:
                          limit:
                            type: integer
                            example: 300
                          used:
                            type: integer
                            example: 45
                          remaining:
                            type: integer
                            example: 255
                          utilization:
                            type: number
                            example: 15
                      daily:
                        type: object
                        properties:
                          limit:
                            type: integer
                            example: 500000
                          used:
                            type: integer
                            example: 12500
                          remaining:
                            type: integer
                            example: 487500
                          utilization:
                            type: number
                            example: 2.5
                  concurrency:
                    type: object
                    properties:
                      current:
                        type: integer
                        example: 0
                      peak:
                        type: integer
                        example: 23
                      active_reservations:
                        type: integer
                        example: 0
                  stats:
                    type: object
                    properties:
                      today:
                        type: object
                        properties:
                          requests:
                            type: integer
                            example: 1250
                          credits:
                            type: number
                            example: 875.5
                          chargeable_requests:
                            type: integer
                            example: 1100
                          chargeable_rate:
                            type: number
                            example: 88
                          unique_products:
                            type: integer
                            example: 5
                      this_week:
                        type: object
                        properties:
                          requests:
                            type: integer
                            example: 8500
                          credits:
                            type: number
                            example: 5200.25
                          chargeable_requests:
                            type: integer
                            example: 7200
                          chargeable_rate:
                            type: number
                            example: 84.7
                          unique_products:
                            type: integer
                            example: 8
                      this_month:
                        type: object
                        properties:
                          requests:
                            type: integer
                            example: 45000
                          credits:
                            type: number
                            example: 28500
                          chargeable_requests:
                            type: integer
                            example: 38000
                          chargeable_rate:
                            type: number
                            example: 84.4
                          unique_products:
                            type: integer
                            example: 12
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: |
        Unauthorized - Authentication failed.

        **Common causes:**
        - Missing X-API-Key header
        - Invalid or expired API key
        - Malformed API key
      content:
        application/problem+json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/MissingAuthenticationError'
              - $ref: '#/components/schemas/InvalidApiKeyError'
  schemas:
    MissingAuthenticationError:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
      example:
        success: false
        errors:
          - type: https://api.leadmagic.io/errors/missing_authentication
            title: >-
              Authentication required. Provide a valid API key in the X-API-Key
              header (case-insensitive).
            status: 401
            code: missing_authentication
            docs: https://leadmagic.io/docs/api-reference/authentication
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
    InvalidApiKeyError:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
      example:
        success: false
        errors:
          - type: https://api.leadmagic.io/errors/invalid_api_key
            title: Invalid API key. The key does not exist or is incorrect.
            status: 401
            code: invalid_api_key
            docs: https://leadmagic.io/docs/api-reference/authentication
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
    ErrorResponse:
      type: object
      description: RFC 9457 Problem Details error response
      required:
        - success
        - errors
      properties:
        success:
          type: boolean
          example: false
          description: Always false for error responses
        errors:
          type: array
          description: Array of error details (typically one, but can be multiple)
          items:
            $ref: '#/components/schemas/ErrorDetail'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    ErrorDetail:
      type: object
      description: RFC 9457 compliant error detail
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
          description: RFC 9457 - URI reference identifying the error type
          example: https://api.leadmagic.io/errors/validation_error
        title:
          type: string
          description: RFC 9457 - Short human-readable summary
          example: Request validation failed. Check your input parameters.
        status:
          type: integer
          description: RFC 9457 - HTTP status code
          example: 400
        detail:
          type: string
          description: RFC 9457 - Human-readable explanation specific to this occurrence
          example: The email field is required but was not provided.
        instance:
          type: string
          format: uri
          description: RFC 9457 - URI reference for this specific occurrence
          example: /v1/people/email-validation#req_abc123
        code:
          type: string
          description: Machine-readable error code for programmatic handling
          example: validation_error
        param:
          type: array
          description: Parameters that caused the error
          items:
            type: string
          example:
            - email
        action:
          type: string
          description: Suggested action to resolve the error
          example: Provide a valid email address in the 'email' field.
        docs:
          type: string
          format: uri
          description: Link to relevant documentation
          example: https://leadmagic.io/docs/api-reference/errors
        context:
          type: object
          description: Additional context specific to this error type
          additionalProperties: true
    ResponseMeta:
      type: object
      description: Metadata included in all responses
      properties:
        request_id:
          type: string
          format: uuid
          description: Unique identifier for this request (use for debugging/support)
          example: ea6e3248-f4d2-437d-bca3-20881b529129
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the response was generated
          example: '2024-02-01T12:00:00.000Z'
        environment:
          type: string
          description: API environment (production, staging)
          example: production
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your LeadMagic API key. Header name is case-insensitive (X-API-Key,
        X-API-KEY, x-api-key all work).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.