Run API Shield schema learning now: traffic thresholds still apply

You can run it now if your account is eligible

On October 12, 2026, Cloudflare announced manual schema learning for API Shield. A schema captures fields, types and constraints from observed API requests. A manual run lets a team start after representative traffic is ready, without waiting for the weekly job. The announcement provides a date, but no exact launch time.

The plans documentation makes Schema Profiles through learning and validation available to API Security customers. Enterprise customers without API Security need an invitation to the closed beta and can contact their account team. Schema upload allowances on Free or Pro do not establish access to learning.

Check your current plan, feature eligibility and permissions for access to the control. The announcement does not specify a per-run price or a new country availability list. A visible button does not establish that the feature is free or available to every account worldwide.

1,000 requests for fields; 10,000 for boundaries

Schema learning uses qualifying requests from the previous seven days. Cloudflare says only requests with 2xx responses count. For each operation, field learning requires 1,000 requests and boundary learning requires 10,000. Manual runs retain these thresholds and cannot produce a usable schema for an operation that lacks enough qualifying traffic.

Enable profile learning for the operations you need, then prepare representative requests. Field learning identifies fields and types; boundary learning needs more data to establish constraints. The two thresholds do not mean every API needs only 1,000 requests.

For a hypothetical example, an operation selected for learning has 999 qualifying 2xx requests and another 500 requests returning 4xx errors. This example has not been executed. The total exceeds 1,000, but field learning still lacks enough qualifying requests. Fixing the errors and checking eligible traffic is more useful than repeatedly clicking Run.

Start from Operations; the run covers the zone

Step 1: In the Cloudflare dashboard, open Web Assets → Operations. Select Learn profile from the target operation’s overflow menu to enable profile learning, or confirm its status if already enabled. Seeing a path in the table does not establish that it is selected for learning.

Step 2: Choose Ad-hoc learn schema from the operation table’s More options menu. In the Schema learning dialog, select Run learning. A zone is the site area the task covers: the run processes its operations selected for learning, rather than only the row whose menu you opened.

Step 3: Check the task status and the zone’s Last completed run in that dialog. A manual run processes traffic already observed; it does not generate test requests. If you need to prepare traffic, use representative requests in a testing environment you are authorized to operate. Production load testing is not a prerequisite for enabling the feature.

Read the status before deciding to retry

Running includes both queueing and processing, so it does not mean every operation has finished. Idle means there is no active task. Waiting to retry means the existing task is awaiting a retry. When the button is unavailable during a run or retry wait, inspect that task rather than repeatedly trying to create another.

A Retry in countdown concerns the request limit, not a guaranteed completion time for the whole learning task. Duration depends on traffic and other factors. Some operations can produce results before the zone-wide task finishes.

For an operation, open View details → Security overview → Schema validation → View → Learned schema. Schema learned, No usable traffic, Learning failed and no result yet have different meanings. For unusable traffic, check selection for learning and qualifying requests first. An empty result is not a successful learned schema.

Review the schema before choosing to block

After learning completes, review whether the fields, types and constraints fit normal requests. Observed traffic supplies the learning material; it does not replace your API contract. Applying constraints from unrepresentative traffic can misclassify legitimate requests.

Cloudflare documents ongoing detection after a profile is learned, but detection itself does not mitigate or block requests. Blocking requires separate Custom Rules. Confirm learning, violation detection and blocking separately; a single learning run does not establish that protection is fully configured.

Have the API owner review the result, then decide whether to create blocking rules through your existing change process. This is an operational recommendation, not an automatic deployment step added by the announcement. A successful learning task also does not establish acceptance of your real business requests.

An export is a snapshot; your next step depends on the result

When your plan supports it, you can export the learned profile as OpenAPI 3.0.0 JSON. The export is a point-in-time snapshot. It does not change the existing learning profile or prove that new requests have passed validation. Check export availability for your plan rather than inferring it from a visible learning button.

With a usable schema, review normal requests and constraints. With No usable traffic, check selected operations and qualifying requests in the seven-day window. With a failure or insufficient permissions, keep the current status and ask your account team or official support to clarify the cause. Choosing the next step from the actual result is clearer than always waiting until next week or always retrying.