Last updated: November 1, 2026
Grok API moderation got a new control on October 27, 2026: a guidelines array on Chat Completions and Responses API requests. It tells Grok to decline nsfw, violence or profanity content as it writes. Categories you leave out keep default behavior, and guidelines apply only to the request that carries them.
Contents
- What’s new
- Categories and behaviors
- How to turn on Grok API moderation
- SDK and endpoint details
- Requests that cannot use guidelines
- Errors to handle
- Pair guidelines with safety_identifier
- How it compares with Gemini safety settings
- Practical workflows and limitations
- Frequently asked questions
What’s new in Grok API moderation
The xAI API release notes entry dated October 27, 2026 says developers “can now set content guidelines on text API requests.” You add a guidelines array to a request, and Grok follows it while it generates the answer, in its own words.
Before this release, you relied on the model’s default behavior plus your own system prompt or filter. Now it is a documented request field with defined categories and errors, per the Custom Moderation Controls guide.
The feature pairs with safety_identifier, a field added on September 25, 2026 that ties policy violations to your end users rather than your API key. Both are covered below.
Categories and behaviors
Each entry in guidelines has three fields: type, which is always policy; a category; and a behavior. Today the only behavior is decline.
| Category | Behavior | What Grok does, per xAI |
|---|---|---|
nsfw |
decline |
Avoids sexual innuendo or sexualized conversations, but still answers educational and clinical questions about sexual topics. |
violence |
decline |
Avoids depictions of graphic violence, but engages with history and news without graphic detail. |
profanity |
decline |
Writes without profanity, and declines when the request is for profanity alone or is highly offensive. |
xAI describes these behaviors at a high level and says it may refine the details over time, so test your own prompts rather than assuming exact boundaries.
How to turn on Grok API moderation
- Use a text model on the xAI API, such as
grok-4.7, through the Responses API (https://api.x.ai/v1/responses) or Chat Completions. - Add a top-level
guidelinesarray to the request body, at the same level asinputormessages. - Add one object per category you want to change, for example
{"type": "policy", "category": "violence", "behavior": "decline"}. - List each category only once; a duplicate category returns HTTP 400.
- Send the same array on every request in the conversation, since guidelines do not carry over between requests.
- Handle 400 and 422 errors, which the API returns before the model runs if it cannot apply the guidelines.
A minimal curl body looks like {"model": "grok-4.7", "input": "Write a short story about a knight.", "guidelines": [{"type": "policy", "category": "violence", "behavior": "decline"}]}. The response has the same shape as one without guidelines, so your parsing code does not change.
SDK and endpoint details
- OpenAI Python SDK: the SDK does not define
guidelines, so pass it insideextra_bodywithbase_urlset tohttps://api.x.ai/v1. - OpenAI JavaScript SDK: pass it with the other request parameters; the SDK sends it through.
- xAI Python SDK: pass
guidelinestochat.create. The SDK stores them on the chat, so everysamplecall sends them. - Chat Completions: add the array as a top-level field next to
messages.
If you are still deciding which Grok surface to build on, our explainer on whether Grok is free covers consumer plans, and the Grok Voice 3.0 guide covers the separate speech-to-speech API, where xAI documents guidelines only for text requests.
Requests that cannot use guidelines
The documentation lists three cases that the API rejects with HTTP 400 before the model runs:
- Multi-agent models, such as
grok-4.20-multi-agent. - Deferred completions.
- A request with no server-side tools and no file attachments that sets
stopor setsngreater than 1.
The error message names the model or option that caused the rejection, which makes these easy to catch in tests.
Errors to handle
| Status | Cause |
|---|---|
| 422 | The category or behavior is not a known value; the error lists valid values. |
| 400 | The same category appears more than once. |
| 400 | The type is not policy. |
| 400 | The request type cannot use guidelines, as described above. |
In the xAI Python SDK, an unknown category or behavior raises ValueError before the request is sent, and the other errors come back as a gRPC INVALID_ARGUMENT status.
Pair guidelines with safety_identifier
According to the xAI security FAQ, safety_identifier is an opaque, stable string your app assigns to the end user behind a request. When a request violates xAI’s usage policies, xAI can attribute it to that identifier instead of your whole API key. xAI says the field is the same as OpenAI’s safety_identifier, which helps if you also route traffic to models like GPT-6.1 Terra.
Send a hash of your internal user ID, never an email address, phone number or display name; xAI does not validate the format. The field works on Chat Completions, the Responses API (including streaming and WebSocket mode), deferred chat completions, the Batch API and gRPC. The legacy user field is still accepted. Gateways that route many users through one key should set it per end user. For data handling, see our answer on whether Grok trains on your data.
How it compares with Gemini safety settings
Google’s Gemini API safety settings take a different approach. Gemini rates content by probability of being unsafe and blocks it at a threshold you choose: off, block few, block some or block most. Its adjustable categories are harassment, hate speech, sexually explicit, dangerous content and jailbreak, and Google says the extra filters are off by default.
| Aspect | Grok guidelines | Gemini safety settings |
|---|---|---|
| Mechanism | Model declines the category as it writes | Blocks content above a probability threshold |
| Categories | nsfw, violence, profanity | Harassment, hate speech, sexually explicit, dangerous, jailbreak |
| Levels | One behavior: decline | Off, block few, block some, block most |
| Response shape | Unchanged | Blocked content is not returned |
In practice, Grok guidelines suit apps that want a polite in-character refusal or a clean rewrite, while Gemini thresholds suit apps that want hard blocking with tunable sensitivity. Our Gemini API CLI guide covers testing Gemini requests from the terminal.
Practical workflows and limitations
- Family-safe chat: set all three categories to
declinein a shared request builder so no code path forgets them. - Brand voice: use only
profanitywhen you want edgy humor without swearing, leaving other defaults alone.
Limitations: only three categories and one behavior exist today, guidelines apply to text requests, and they add restrictions on top of default moderation rather than relaxing it.
Frequently asked questions
Does the Grok API have moderation controls?
Yes. Since October 27, 2026, the xAI API accepts a guidelines array on Chat Completions and Responses API requests. It lets you tell Grok to decline content in the nsfw, violence and profanity categories, on top of the model’s default moderation.
What categories can I set with Grok guidelines?
Three categories are documented: nsfw, violence and profanity. The only behavior available today is decline. Categories you leave out keep the model’s default behavior.
Do Grok guidelines apply to a whole conversation?
No. Guidelines apply only to the request that carries them, so you must send them on every request. In the xAI Python SDK, chat.create stores them on the chat, so every sample call sends them automatically.
Which requests cannot use guidelines?
Multi-agent models such as grok-4.20-multi-agent and deferred completions do not support guidelines. A request with no server-side tools and no file attachments also cannot use them if it sets stop or sets n greater than 1. These requests are rejected with HTTP 400.
What is safety_identifier in the xAI API?
It is an opaque, stable string your application assigns to each end user, added on September 25, 2026. If a request violates xAI’s usage policies, xAI can attribute it to that identifier instead of your whole API key. xAI says to send a hash, never an email address or name.
How is this different from Gemini safety settings?
Gemini’s adjustable filters block content by probability thresholds in categories such as harassment, hate speech, sexually explicit and dangerous content. Grok guidelines instead tell the model to decline a category while it writes, and the response keeps its normal shape.
Sources
- xAI Docs: Custom Moderation Controls
- xAI Docs: Release Notes
- xAI Docs: Security FAQ
- Google AI for Developers: Gemini API safety settings
Image: Grok logo by xAI, public domain, via Wikimedia Commons. Placed on a white background and resized. FreeAnswers is not affiliated with xAI.
