# Cloudflare HTTP Requests

Ingests Cloudflare HTTP request analytics using the GraphQL Analytics API. This input collects detailed information about HTTP requests processed by Cloudflare, including client information, response metrics, caching details, and security data from the `httpRequestsAdaptive` dataset.

**Sync Type: Incremental**

## Requirements

- A Cloudflare account with access to the Analytics API
- An API Token with the `Account Analytics:Read` permission
- Your Cloudflare Zone ID

### Data Retention by Plan

Cloudflare retains HTTP request analytics based on your plan:

| Plan | Data Retention |
|------|----------------|
| Free | 24 hours |
| Pro | 3 days |
| Business | 3-30 days |
| Enterprise | 30-90 days |

The input automatically detects your plan's retention limits and adjusts queries accordingly.

### Creating an API Token

1. Log in to your Cloudflare dashboard
2. Navigate to **My Profile** > **API Tokens**
3. Click **Create Token**
4. Use the **Create Custom Token** option
5. Configure the token:
   - **Token name**: Give it a descriptive name (e.g., "Monad HTTP Requests Analytics")
   - **Permissions**: Add `Account` > `Account Analytics` > `Read`
   - **Zone Resources**: Select the specific zone(s) or "All zones"
6. Click **Continue to summary** and then **Create Token**
7. Copy the token value (you won't be able to see it again)

### Finding Your Zone ID

1. Log in to your Cloudflare dashboard
2. Select the domain/zone you want to monitor
3. The Zone ID is displayed in the right sidebar on the overview page
4. It's a 32-character alphanumeric string

## Details

- **State Management**: Uses timestamp-based incremental sync. Monad stores the last processed event timestamp to fetch only new events on subsequent runs.
- **API Endpoint**: GraphQL Analytics API (`/graphql`)
- **Dataset**: `httpRequestsAdaptive`
- **Pagination**: Time-window based pagination. The API defines maximum query duration (`maxDuration`) to prevent timeout. The input automatically chunks requests into time windows to handle large time ranges.
- **Rate Limits**: 300 requests per 5 minutes (1 request per second). The input automatically enforces this limit.
- **Field Selection**: The dataset has over 120 available fields. Up to 49 user-selectable fields can be included (datetime is always included implicitly for state management, making 50 fields total). The input validates requested fields against your account's available fields at runtime.
- **Adaptive Sampling**: During high-traffic periods, Cloudflare may apply sampling to this dataset. Not all events may be returned during very high volume periods.

## Configuration

### Settings

| Setting | Type | Required | Description |
|---------|------|----------|-------------|
| `zone_id` | string | Yes | Cloudflare Zone ID (32-character alphanumeric string) |
| `fields` | array | No | Array of field names to include in the query. Leave empty to use a curated default set of important fields. Only fields available to your account will be included (validated at runtime). Maximum 49 user-selectable fields (datetime is always included automatically for 50 total). Enum includes ~120 known fields: `clientIP`, `clientAsn`, `clientCountryName`, `clientDeviceType`, `clientIP`, `clientIPClass`, `clientMTLSAuthCertFingerprint`, `clientMTLSAuthStatus`, `clientRefererHost`, `clientRefererPath`, `clientRefererQuery`, `clientRefererScheme`, `clientRequestBytes`, `clientRequestHTTPHost`, `clientRequestHTTPMethodName`, `clientRequestHTTPProtocol`, `clientRequestPath`, `clientRequestQuery`, `clientRequestReferer`, `clientRequestScheme`, `clientRequestSource`, `clientRequestURI`, `clientSSLCipher`, `clientSSLProtocol`, `clientSrcPort`, `clientTCPRTTMs`, `clientXRequestedWith`, `coloCode`, `edgeColoCode`, `edgeColoID`, `edgeColoName`, `edgeEndTimestamp`, `edgeRateLimitAction`, `edgeRateLimitID`, `edgeRequestHost`, `edgeResponseBodyBytes`, `edgeResponseBytes`, `edgeResponseCompressionRatio`, `edgeResponseContentType`, `edgeResponseStatus`, `edgeServerIP`, `edgeStartTimestamp`, `edgeTimeToFirstByteMs`, `cacheStatus`, `cacheCacheStatus`, `cacheTieredFill`, `cacheReserveUsed`, `originASN`, `originIP`, `originResponseBytes`, `originResponseDurationMs`, `originResponseHTTPExpires`, `originResponseHTTPLastModified`, `originResponseStatus`, `originResponseTime`, `originSSLProtocol`, `botScore`, `botScoreSrcName`, `botManagementDecision`, `ja3Hash`, `ja4`, `securityAction`, `securityActions`, `securityRuleDescription`, `securityRuleID`, `securityRuleIDs`, `securitySources`, `wafAttackScore`, `wafFlags`, `wafMatchedVar`, `wafProfile`, `wafRCEAttackScore`, `wafSQLiAttackScore`, `wafXSSAttackScore`, `requestHeaders`, `responseHeaders`, `upperTierColoName`, `userAgent`, `workerCPUTime`, `workerStatus`, `workerSubrequest`, `workerSubrequestCount`, `workerWallTimeUs`, `xRequestedWith`, `zoneID`, `zoneName`, `tlsCipher`, `tlsClientHelloLength`, `tlsClientRandom`, `tlsVersion`, `firewallMatchesActions`, `firewallMatchesRuleIDs`, `firewallMatchesSources`, `contentScanHasMaliciousPayload`, `contentScanNumMaliciousObj`, `contentScanNumObj`, `contentScanObjResults`, `contentScanObjTypes`, `leakyBucketActions`, `leakyBucketConfigurationIDs`, `leakyBucketMitigations`, `smartColoConnectTimeMs`, `smartColoID` |
| `lookback_duration` | string | No | Initial lookback duration for first sync (e.g., `24h`, `7d`). Must not exceed your plan's data retention limit. Default: 5 minutes if not specified |
| API Rate Limit | object | No | Optional limit on the connector's outbound request rate to the source API. Leave blank to use the connector's default behavior. See [API Rate Limiting](../../../guides/rate-limiting) for the field format, limits, and how to choose a value. |

### Secrets

| Secret | Type | Required | Description |
|--------|------|----------|-------------|
| `api_token` | string | Yes | API Token with Account Analytics:Read permission |

### Rate Limits

| Limit | Value | Notes |
|-------|-------|-------|
| Requests per 5 minutes | 300 | GraphQL Analytics API limit |
| Requests per second | 1 | Enforced by rate limiter |
| Max records per query | Plan-dependent | Discovered automatically via Settings API |

**Source**: [Cloudflare GraphQL Analytics API Limits](https://developers.cloudflare.com/analytics/graphql-api/limits/)

## Troubleshooting

### Common Issues

**Issue**: `GraphQL error` with authentication message
**Cause**: The API token is invalid, expired, or lacks the required permissions.
**Solution**: Verify your API token is correct and has the `Account Analytics:Read` permission. Create a new token if needed.

**Issue**: `Zone ID is required` validation error
**Cause**: The Zone ID field was left empty.
**Solution**: Enter your Cloudflare Zone ID in the settings. You can find this in your Cloudflare dashboard under the zone's overview page.

**Issue**: `invalid settings response` error
**Cause**: The Zone ID is incorrect or the API token doesn't have access to that zone.
**Solution**: Verify the Zone ID is correct and that your API token has permissions for that specific zone.

**Issue**: No data returned despite having HTTP traffic
**Cause**: The lookback duration may exceed your plan's data retention, or there may be no requests in the time range.
**Solution**: Check your plan's data retention limits. Free plans only retain 24 hours of data.

**Issue**: `unknown field` validation error
**Cause**: A requested field is not available to your account or is misspelled.
**Solution**: Check that all field names are spelled correctly and are available to your account. Some fields require specific plan levels or add-ons.

**Issue**: `maximum 49 fields allowed` error
**Cause**: More than 49 user-selectable fields were requested (datetime is included automatically).
**Solution**: Reduce the number of requested fields to 49 or fewer.

**Issue**: Requests appear to be missing during high traffic
**Cause**: Cloudflare applies adaptive sampling to this dataset during high-volume periods.
**Solution**: This is expected behavior. The dataset is designed for monitoring and analysis, not exact request counting.

**Issue**: `invalid lookback_duration format` error
**Cause**: The lookback duration is not in a valid Go duration format.
**Solution**: Use valid duration formats like `24h`, `7d`, `1h30m`, etc.

## Related Articles

- [Cloudflare GraphQL Analytics API](https://developers.cloudflare.com/analytics/graphql-api/)
- [Querying HTTP Request Analytics with GraphQL](https://developers.cloudflare.com/analytics/graphql-api/tutorials/querying-http-requests/)
- [Cloudflare API Tokens](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/)
- [GraphQL Analytics API Limits](https://developers.cloudflare.com/analytics/graphql-api/limits/)

## Sample Record

```json
{
  "cacheStatus": "hit",
  "clientAsn": 65001,
  "clientCountryName": "United States",
  "clientIP": "198.51.100.42",
  "clientRequestHTTPHost": "api.example.com",
  "clientRequestHTTPMethodName": "GET",
  "clientRequestPath": "/api/v1/data",
  "clientSSLProtocol": "TLSv1.3",
  "datetime": "2024-01-15T10:30:45Z",
  "edgeResponseStatus": 200,
  "edgeResponseBytes": 4096,
  "originIP": "192.0.2.10",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}
```