Learn expected request fields and constraints from qualifying operation traffic.
-
In the Cloudflare dashboard, go to Web Assets > Operations.
Go to Web assets ↗ -
Open the operation overflow menu and select Learn profile.
-
After the profile becomes available, select View details.
-
Follow the steps to review learning results.
Cloudflare runs an always-on detection after the learned profile becomes available. The detection does not mitigate requests by itself.
To investigate results, refer to Analyze profile detections. To mitigate violations, refer to Enforce profiles with Custom Rules.
Learning runs weekly using qualifying traffic from the previous seven days. Only requests that received a 2xx response contribute.
The field-learning threshold requires 1,000 qualifying requests. The boundary-learning threshold requires 10,000 qualifying requests.
With scheduled learning, the first profile appears after the next weekly run. This can take up to seven days after meeting the relevant threshold. You can also request a learning run manually.
For supported request components, constraints, and limitations, refer to Schema Profiles.
Request an ad-hoc learning run without waiting for the weekly schedule. For example, request a run after sending representative traffic during testing.
The run covers the entire zone, rather than one operation. It uses observed traffic and does not generate requests. Operations must be selected for profile learning and meet the learning requirements.
-
In the Cloudflare dashboard, go to Web Assets > Operations.
Go to Web assets ↗ -
Open the More options menu for the operations table.
-
Select Ad-hoc learn schema to open the Schema learning dialog.
-
Select Run learning to request a zone-wide run.
The dialog shows the learning status and Last completed run for the zone. Running includes time waiting for processing. Idle means no run is active. Waiting to retry means Cloudflare is waiting to retry an existing run.
The run button is unavailable while a run is active or waiting to retry. If the button shows Retry in, wait before requesting another run. The countdown limits manual requests and does not predict when learning finishes.
If you have read-only access, the menu shows Schema learning. You can view the status but cannot request a run.
Completion time depends on traffic volume. Individual operations can finish before the entire zone-wide run completes.
- From the overflow menu for an operation, select View details.
- In Security overview > Schema validation, select View.
- Select Learned schema.
- Review Schema learning result and Last learning run to check whether that operation has been processed.
The result shows one of these outcomes:
| Outcome | Meaning |
|---|---|
| Schema learned | Cloudflare learned a schema for the operation. |
| No usable traffic | The run found no usable traffic for the operation. |
| Learning failed | The learning attempt for the operation failed. |
No learning result recorded means no result is available yet. Review the learned schema before enforcing its detection.
Export availability depends on your plan. Each export creates a point-in-time OpenAPI file from the current learned profile. It does not change the profile or its detection.
-
In the Cloudflare dashboard, go to the Web Assets page.
Go to Web assets ↗ -
Go to the Operations tab.
-
Select Export schema and choose a hostname to export.
-
Select whether to include learned parameters and rate limit recommendations.
-
Select Export schema and choose a location to save the file.
Exported schemas include the listed hostname in the servers section. They also include operations by hostname, method, and path.
For operations that receive sufficient traffic, exported schemas also include:
- Detected path variables and formats
- Detected query parameters and formats
- Detected
POST,PUT, andPATCHbody variable names and formats forapplication/jsoncontent types
Exported schemas can optionally include API Shield rate limit recommendations.
For a fixed Schema Profile, upload the exported file through Schema validation.