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

# API Key Logs

> Retrieve activity logs for your API keys to monitor usage and track requests.

### Headers

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

### Query Parameters

<ParamField query="api_key_id" type="number">
  Filter logs by a specific API key ID.
</ParamField>

<ParamField query="page" type="number" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="limit" type="number" default="10">
  Number of log entries to return per page.
</ParamField>

<ParamField query="start_date" type="string">
  Filter logs from this date onwards (ISO 8601 format, e.g., `2025-11-01T00:00:00Z`).
</ParamField>

<ParamField query="end_date" type="string">
  Filter logs up to this date (ISO 8601 format, e.g., `2025-11-30T23:59:59Z`).
</ParamField>

<ParamField query="status_code" type="number">
  Filter by HTTP status code (e.g., `200`, `429`, `500`).
</ParamField>

<ParamField query="endpoint" type="string">
  Filter by specific endpoint path (e.g., `/v1/send`, `/v1/domains`).
</ParamField>

### Response

<ResponseField name="status" type="number">
  HTTP status code. Returns `200` when logs are retrieved successfully.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable message describing the result of the operation.
</ResponseField>

<ResponseField name="data" type="object">
  Contains the paginated list of API key logs and pagination metadata.

  <Expandable title="properties">
    <ResponseField name="data" type="array">
      Array of API key log entries.

      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Unique identifier for the log entry.
        </ResponseField>

        <ResponseField name="api_key_id" type="number">
          The ID of the API key used for this request.
        </ResponseField>

        <ResponseField name="team_id" type="string">
          The team ID that owns the API key.
        </ResponseField>

        <ResponseField name="endpoint" type="string">
          The API endpoint that was called (e.g., `/v1/send`, `/v1/emails`, `/v1/domains`). For SMTP requests, this will be `smtp`.
        </ResponseField>

        <ResponseField name="method" type="string">
          HTTP method used for the request. Possible values: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`. For SMTP requests, this will be `SMTP`.
        </ResponseField>

        <ResponseField name="status_code" type="number">
          HTTP status code returned by the API (e.g., `200`, `201`, `400`, `429`, `500`).
        </ResponseField>

        <ResponseField name="ip_address" type="string">
          IP address from which the request originated.
        </ResponseField>

        <ResponseField name="user_agent" type="string">
          User agent string from the client that made the request.
        </ResponseField>

        <ResponseField name="request_body" type="object | null">
          The request payload sent to the API. Sensitive data may be redacted. Null for GET requests.
        </ResponseField>

        <ResponseField name="response_body" type="object | null">
          The API response. May be truncated for large responses.
        </ResponseField>

        <ResponseField name="response_time" type="number">
          Time taken to process the request in milliseconds.
        </ResponseField>

        <ResponseField name="error_message" type="string | null">
          Error message if the request failed. Null for successful requests.
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO 8601 timestamp when the request was made.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="pagination" type="object">
      Pagination metadata.

      <Expandable title="properties">
        <ResponseField name="page" type="number">
          Current page number.
        </ResponseField>

        <ResponseField name="total_records" type="number">
          Total number of log entries across all pages.
        </ResponseField>

        <ResponseField name="total_pages" type="number">
          Total number of pages available.
        </ResponseField>

        <ResponseField name="limit" type="number">
          Number of records per page.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
      "status": 200,
      "message": "api key logs retrieved successfully.",
      "data": {
          "data": [
              {
                  "id": "xxxxx",
                  "api_key_id": 2,
                  "team_id": "xxxxx",
                  "endpoint": "/v1/send",
                  "method": "POST",
                  "status_code": 201,
                  "ip_address": "xxx.xxx.xxx.xxx",
                  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
                  "request_body": {
                      "to": "user@example.com",
                      "subject": "Welcome Email",
                      "body": "<redacted>"
                  },
                  "response_body": {
                      "status": 201,
                      "message": "email sent successfully"
                  },
                  "response_time": 245,
                  "error_message": null,
                  "created_at": "2025-11-21T14:30:15.123Z"
              },
              {
                  "id": "xxxxx",
                  "api_key_id": 2,
                  "team_id": "xxxxx",
                  "endpoint": "/v1/emails",
                  "method": "GET",
                  "status_code": 200,
                  "ip_address": "xxx.xxx.xxx.xxx",
                  "user_agent": "axios/1.6.0",
                  "request_body": null,
                  "response_body": {
                      "status": 200,
                      "message": "emails retrieved successfully"
                  },
                  "response_time": 89,
                  "error_message": null,
                  "created_at": "2025-11-21T14:25:42.456Z"
              },
              {
                  "id": "xxxxx",
                  "api_key_id": 2,
                  "team_id": "xxxxx",
                  "endpoint": "/v1/send",
                  "method": "POST",
                  "status_code": 429,
                  "ip_address": "xxx.xxx.xxx.xxx",
                  "user_agent": "node-fetch/2.6.1",
                  "request_body": {
                      "to": "user@example.com",
                      "subject": "Test Email",
                      "body": "<redacted>"
                  },
                  "response_body": {
                      "status": 429,
                      "message": "Rate limit exceeded. Please try again later."
                  },
                  "response_time": 12,
                  "error_message": "Rate limit exceeded",
                  "created_at": "2025-11-21T14:20:05.789Z"
              },
              {
                  "id": "xxxxx",
                  "api_key_id": 2,
                  "team_id": "xxxxx",
                  "endpoint": "smtp",
                  "method": "SMTP",
                  "status_code": 200,
                  "ip_address": "xxx.xxx.xxx.xxx",
                  "user_agent": "nodemailer/6.9.7",
                  "request_body": {
                      "to": "recipient@example.com",
                      "subject": "SMTP Test",
                      "body": "<redacted>"
                  },
                  "response_body": {
                      "status": 200,
                      "message": "Email sent via SMTP"
                  },
                  "response_time": 310,
                  "error_message": null,
                  "created_at": "2025-11-21T14:15:30.123Z"
              },
              {
                  "id": "xxxxx",
                  "api_key_id": 2,
                  "team_id": "xxxxx",
                  "endpoint": "/v1/domains",
                  "method": "POST",
                  "status_code": 201,
                  "ip_address": "xxx.xxx.xxx.xxx",
                  "user_agent": "curl/8.4.0",
                  "request_body": {
                      "value": "example.com"
                  },
                  "response_body": {
                      "status": 201,
                      "message": "domain added successfully"
                  },
                  "response_time": 156,
                  "error_message": null,
                  "created_at": "2025-11-21T14:10:22.789Z"
              }
          ],
          "pagination": {
              "page": 1,
              "total_records": 250,
              "total_pages": 25,
              "limit": 10
          }
      }
  }
  ```
</ResponseExample>

## Use Cases

### Monitor API Key Usage

Track how your API keys are being used across different endpoints:

```javascript theme={null}
// Get all logs for a specific API key
const response = await fetch('https://api.thepurplebox.io/v1/api-keys/logs?api_key_id=2&limit=50', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const logs = await response.json();
console.log(`Total requests: ${logs.data.pagination.total_records}`);
```

### Identify Rate Limit Issues

Find when and why rate limits are being hit:

```javascript theme={null}
// Filter by 429 status codes
const response = await fetch('https://api.thepurplebox.io/v1/api-keys/logs?status_code=429', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const rateLimitErrors = await response.json();
rateLimitErrors.data.data.forEach(log => {
  console.log(`Rate limit hit at ${log.created_at} on ${log.endpoint}`);
});
```

### Audit Security

Monitor requests from unexpected IP addresses or locations:

```javascript theme={null}
// Get recent logs and check IP addresses
const response = await fetch('https://api.thepurplebox.io/v1/api-keys/logs?limit=100', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const logs = await response.json();
const uniqueIPs = [...new Set(logs.data.data.map(log => log.ip_address))];
console.log('Requests from IPs:', uniqueIPs);
```

### Debug Failed Requests

Investigate errors and failed API calls:

```javascript theme={null}
// Filter by error status codes (4xx and 5xx)
const response = await fetch('https://api.thepurplebox.io/v1/api-keys/logs?start_date=2025-11-20T00:00:00Z', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const logs = await response.json();
const errors = logs.data.data.filter(log => log.status_code >= 400);
errors.forEach(log => {
  console.log(`Error: ${log.status_code} - ${log.error_message}`);
  console.log(`Endpoint: ${log.method} ${log.endpoint}`);
  console.log(`Time: ${log.created_at}`);
});
```

## Log Retention

API key logs are retained for:

* **Free Plan**: 1 day
* **Basic Plan**: 3 days
* **Other Plans**: Check our [pricing page](https://thepurplebox.io/pricing) for retention details

## What Gets Logged

API key usage is logged for **all operations**, including:

* **REST API Requests**: Any HTTP request to our API endpoints (`/v1/send`, `/v1/emails`, `/v1/domains`, etc.)
* **SMTP Authentication**: Emails sent via SMTP using your API key as the password
* **All API Operations**: Domain creation/verification, email retrieval, contact management, and any other API functionality

This comprehensive logging helps you monitor all activity associated with your API keys, regardless of how they're being used.

## Privacy & Security

* Sensitive data in request/response bodies may be redacted
* IP addresses are logged for security purposes
* Logs are only accessible by team members with proper authentication
* All log data is encrypted at rest and in transit