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

# API Access

> Access your FAII data programmatically - build custom integrations, dashboards, and automated workflows using the FAII API.

<Info>
  **Quick Answer:** The FAII API lets you access all your monitoring data programmatically. Available on Professional and Enterprise plans. Use it for custom dashboards, automated reporting, or integration with other tools.
</Info>

## What You'll Learn

* What the API provides
* How to authenticate
* Available endpoints
* Rate limits and best practices

## API Availability

| Plan         | API Access |      Rate Limit     |
| ------------ | :--------: | :-----------------: |
| Starter      |      ❌     |         N/A         |
| Professional |      ✅     |  100 requests/hour  |
| Enterprise   |      ✅     | 1,000 requests/hour |

## Authentication

### API Key

1. Go to **Account > API** in your dashboard
2. Click **Generate API Key**
3. Copy the key (shown once)
4. Use in the `Authorization` header:

```
Authorization: Bearer your-api-key-here
```

<Warning>
  Keep your API key secret. Don't commit it to code repositories, share in public channels, or expose in client-side code. Treat it like a password.
</Warning>

### Regenerating keys

If your key is compromised:

1. Go to **Account > API**
2. Click **Regenerate Key**
3. Old key is immediately invalidated
4. Update all integrations with the new key

## Available Endpoints

### Campaign Data

| Endpoint                          | Method | Returns                      |
| --------------------------------- | :----: | ---------------------------- |
| `/api/campaigns`                  |   GET  | List all campaigns           |
| `/api/campaigns/{id}`             |   GET  | Campaign details             |
| `/api/campaigns/{id}/sessions`    |   GET  | All session data             |
| `/api/campaigns/{id}/keywords`    |   GET  | Keyword list and performance |
| `/api/campaigns/{id}/competitors` |   GET  | Competitor data              |

### Intelligence Data

| Endpoint                    | Method | Returns                          |
| --------------------------- | :----: | -------------------------------- |
| `/api/campaigns/{id}/chat`  |   GET  | Chat Intelligence results        |
| `/api/campaigns/{id}/serp`  |   GET  | SERP Intelligence results        |
| `/api/campaigns/{id}/score` |   GET  | AI Authority Rank and components |
| `/api/campaigns/{id}/gaps`  |   GET  | Publishing opportunities         |

### AI Website Analytics

| Endpoint                    | Method | Returns              |
| --------------------------- | :----: | -------------------- |
| `/api/analytics/bot-visits` |   GET  | Bot visit data       |
| `/api/analytics/pages`      |   GET  | Page-level analytics |

### Technical Audit

| Endpoint             | Method | Returns                   |
| -------------------- | :----: | ------------------------- |
| `/api/audit/latest`  |   GET  | Most recent audit results |
| `/api/audit/history` |   GET  | All audit results         |

## Response Format

All responses are JSON:

```json theme={null}
{
  "status": "success",
  "data": {
    "campaign_id": "abc-123",
    "score": 52,
    "components": {
      "chat": 48,
      "serp": 55,
      "sentiment": 62,
      "competitive": 45
    },
    "last_session": "2025-01-20T06:00:00Z"
  }
}
```

### Error responses

```json theme={null}
{
  "status": "error",
  "message": "Rate limit exceeded",
  "code": 429
}
```

## Common Use Cases

### Custom dashboards

Build your own visualization of FAII data:

* Pull score data into Tableau or Data Studio
* Create client-specific dashboard views
* Combine with other marketing metrics

### Automated reporting

Generate reports on your schedule:

* Pull data and format as PDF/email
* Send weekly summaries to stakeholders
* Integrate with Slack or Teams notifications

### CI/CD integration

Monitor AI visibility as part of your development workflow:

* Check technical audit grade in CI pipeline
* Alert on score drops after deployments
* Track content impact after publishes

### Multi-client management

For agencies with multiple campaigns:

* Aggregate data across all clients
* Build white-label portals
* Automate client reporting

## Rate Limits

| Plan         |      Limit     |  Window  |
| ------------ | :------------: | :------: |
| Professional |  100 requests  | Per hour |
| Enterprise   | 1,000 requests | Per hour |

### Handling rate limits

When rate limited, the API returns:

* HTTP 429 status code
* `Retry-After` header with seconds to wait
* Error message in response body

Best practices:

* Cache responses when possible
* Use webhooks instead of polling (Enterprise)
* Batch requests where possible
* Implement exponential backoff

## Webhooks (Enterprise)

Instead of polling the API, receive notifications:

| Event                   | Triggered When                        |
| ----------------------- | ------------------------------------- |
| `session.complete`      | A monitoring session finishes         |
| `score.changed`         | AI Authority Rank changes             |
| `displacement.detected` | Competitive displacement occurs       |
| `gap.new`               | New publishing opportunity identified |
| `audit.complete`        | Technical audit finishes              |

Configure webhooks in **Account > API > Webhooks**.

## Tips

* **Start with the score endpoint** - Simplest way to verify your integration works
* **Cache aggressively** - Data only changes after sessions run (weekly)
* **Use pagination** - Large data sets return paginated results
* **Monitor your usage** - Check rate limit headers in responses
* **Secure your key** - Use environment variables, never hardcode

## Related Articles

<CardGroup cols={2}>
  <Card title="Usage Limits" icon="gauge" href="/docs/account/usage-limits">
    Understanding plan limits
  </Card>

  <Card title="Account Settings" icon="gear" href="/docs/account/settings">
    Manage your account
  </Card>
</CardGroup>