Grok

Chat with Grok, X's built-in AI, and manage your Grok conversations. Grok replies stream back from X as newline-delimited JSON; emusks parses that stream into a single result object for you.

TIP

The high-level grok.ask() is all you need for one-shot questions. Use grok.createConversation() + grok.respond() when you want to manage conversation IDs yourself.

grok.ask(message, opts?)

Ask Grok a question. Creates a conversation (unless you pass opts.conversationId), sends the message, and returns the parsed response.

Option	Type	Description
message	string	Your prompt
opts.conversationId	string	Continue an existing conversation instead of creating a new one
opts.model	string	Model option id (default grok-3-latest, see grok.models())
opts.reasoning	boolean	Enable reasoning mode (default false)
opts.deepsearch	boolean	Enable DeepSearch (default false)
opts.systemPromptName	string	Named system prompt
opts.fileAttachments	array	Attachment objects to include with the prompt
opts.returnSearchResults	boolean	Include web search results (default true)
opts.returnCitations	boolean	Include citations (default true)
opts.raw	boolean	Return the raw NDJSON stream as a string
opts.body	object	Merge extra fields into the request body

const res = await client.grok.ask("what's the latest on the falcon 9?");
console.log(res.message);
console.log(res.conversationId);

// continue the same conversation
const followUp = await client.grok.ask("and the booster landing?", {
  conversationId: res.conversationId,
});

// reasoning mode
const math = await client.grok.ask("what is 17 * 23? show your reasoning", {
  reasoning: true,
});
console.log(math.reasoning, math.message);

The returned object:

Field	Type	Description
conversationId	string	The conversation this response belongs to
message	string	The assembled final answer
reasoning	string	The assembled reasoning/thinking trace
followUpSuggestions	array	Suggested follow-up prompts
webResults	array	Web search results, when search was used
citations	array	Citations, when returned
images	array	Generated image attachments, when any
agentChatItemId	string	The response message id (use it to delete)
chunks	array	Every raw parsed line from the stream

grok.respond(conversationId, message, opts?)

Low-level: send a message to an existing conversation. Same opts as ask. Returns the parsed response (without re-wrapping the conversation id).

const id = await client.grok.createConversation();
const res = await client.grok.respond(id, "hello");

grok.createConversation()

Create an empty Grok conversation and return its id. Uses the GraphQL CreateGrokConversation mutation.

const conversationId = await client.grok.createConversation();

grok.home()

Get the Grok home payload: eligibility, default model, and available model options. Uses the GraphQL GrokHome query.

const home = await client.grok.home();
console.log(home.eligible_for_grok, home.default_grok_model_option_id);

grok.models()

Convenience wrapper around grok.home() that returns just the grok_model_options array.

const models = await client.grok.models();
// [{ id: "grok-3-latest", name: "Fast", ... }]

grok.history(opts?)

List your Grok conversations. Uses the GraphQL GrokHistory query.

Option	Type	Description
opts.count	number	Number of results
opts.cursor	string	Pagination cursor

const { items } = await client.grok.history({ count: 20 });

grok.conversation(restId, opts?)

Fetch the items (messages) in a conversation by its rest id. Uses the GraphQL GrokConversationItemsByRestId query.

const conv = await client.grok.conversation("2062645889592938576");
console.log(conv.grok_conversation_items_by_rest_id.items);

grok.mediaHistory(opts?)

List your Grok-generated media. Uses the GraphQL GrokMediaHistory query.

const media = await client.grok.mediaHistory();

grok.search(query, opts?)

Search your Grok conversations. Uses the GraphQL SearchGrokConversations query.

const results = await client.grok.search("falcon 9");

grok.pinned() / grok.pin(conversationId) / grok.unpin(conversationId)

Manage pinned conversations. Use the GraphQL GrokPinnedConversations, GrokPinConversation, and GrokUnpinConversation operations.

await client.grok.pin("2062645889592938576");
const { items } = await client.grok.pinned();
await client.grok.unpin("2062645889592938576");

grok.deleteMessage(conversationId, chatItemId)

Delete a single message from a conversation. Uses the GraphQL DeleteGrokMessage mutation.

const res = await client.grok.ask("hi");
await client.grok.deleteMessage(res.conversationId, res.agentChatItemId);

grok.clear()

Delete all your Grok conversations. Uses the GraphQL ClearGrokConversations mutation.

await client.grok.clear();

grok.share(shareId)

Resolve a shared Grok conversation by its share id. Uses the GraphQL GrokShare query.

const shared = await client.grok.share("some_share_id");

grok.setPreferences(params)

Update your Grok preferences. Uses the GraphQL SetGrokPreferences mutation.

await client.grok.setPreferences({ default_grok_mode: "Normal" });