> ## 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.

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

## 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
```

<CodeGroup>
  ```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)
  ```
</CodeGroup>

### 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

<ResponseField name="user" type="object" required>
  Your account information

  <Expandable title="properties">
    <ResponseField name="id" type="string">Unique user identifier</ResponseField>
    <ResponseField name="email" type="string">Account email address</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="credits" type="object" required>
  Current credit balance

  <Expandable title="properties">
    <ResponseField name="current" type="number">Raw credit balance (1 credit = \$0.01)</ResponseField>
    <ResponseField name="formatted" type="string">Human-readable dollar value</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rate_limit" type="object" required>
  Real-time rate limit status

  <Expandable title="properties">
    <ResponseField name="minute.limit" type="number">Requests per minute allowed</ResponseField>
    <ResponseField name="minute.used" type="number">Requests used this minute</ResponseField>
    <ResponseField name="minute.remaining" type="number">Requests remaining this minute</ResponseField>
    <ResponseField name="minute.utilization" type="number">Percentage of limit used (0-100)</ResponseField>
    <ResponseField name="daily.limit" type="number">Requests per day allowed</ResponseField>
    <ResponseField name="daily.used" type="number">Requests used today</ResponseField>
    <ResponseField name="daily.remaining" type="number">Requests remaining today</ResponseField>
    <ResponseField name="daily.utilization" type="number">Percentage of daily limit used</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="concurrency" type="object" required>
  Concurrent request tracking

  <Expandable title="properties">
    <ResponseField name="current" type="number">Currently in-flight requests</ResponseField>
    <ResponseField name="peak" type="number">Peak concurrent requests (session)</ResponseField>
    <ResponseField name="active_reservations" type="number">Credit reservations pending</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="stats" type="object" required>
  Usage statistics for today, this week, and this month

  <Expandable title="properties">
    <ResponseField name="requests" type="number">Total API requests</ResponseField>
    <ResponseField name="credits" type="number">Total credits consumed</ResponseField>
    <ResponseField name="chargeable_requests" type="number">Requests that consumed credits</ResponseField>
    <ResponseField name="chargeable_rate" type="number">Percentage of requests charged</ResponseField>
    <ResponseField name="unique_products" type="number">Number of different endpoints used</ResponseField>
  </Expandable>
</ResponseField>

***

## 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
```

<ParamField query="days" type="number" default="30">
  Number of days to include (1-90)
</ParamField>

### 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.).
</Tip>

***

## 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
```

<ParamField query="days" type="number" default="30">
  Number of days to include (1-90)
</ParamField>

### 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.
</Warning>

***

## 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
```

<ParamField query="days" type="number" default="30">
  Number of days to include (1-90)
</ParamField>

### 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
```

<ParamField query="start_date" type="string">
  Start date (YYYY-MM-DD format). Optional.
</ParamField>

<ParamField query="end_date" type="string">
  End date (YYYY-MM-DD format). Optional.
</ParamField>

### 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
```

<ParamField query="days" type="number" default="30">
  Number of days to include (1-90)
</ParamField>

### 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

<Tabs>
  <Tab title="Monitoring Dashboard" icon="chart-line">
    ### 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>

  <Tab title="Alerting" icon="bell">
    ### 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>

  <Tab title="Cost Optimization" icon="coins">
    ### 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>

  <Tab title="SLA Monitoring" icon="gauge">
    ### 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
      };
    }
    ```
  </Tab>
</Tabs>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Cache dashboard responses" icon="database">
    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>

  <Accordion title="Use response headers instead" icon="heading">
    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>

  <Accordion title="Batch analytics calls" icon="layer-group">
    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>

  <Accordion title="Set up regular reporting" icon="calendar">
    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 }))
      };
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Check Credits" icon="coins" href="/docs/v1/reference/check-credits">
    Simple endpoint to check your current balance.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/docs/v1/making-api-calls#rate-limits">
    Learn about rate limiting and how to stay within limits.
  </Card>
</CardGroup>


## 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).

````