Running queries

The helper namespaces are built on three raw API layers, and you can call them directly. That's useful for endpoints no helper wraps yet, or when you want the response exactly as Twitter sends it. For Jetfuel routes, see client.jf().

Raw calls return Twitter's responses unparsed. Those are deeply nested, inconsistent and change without warning, which is the work the helpers do for you.

client.graphql(operationName, opts?)

GraphQL powers most features: tweets, users, timelines, communities and more.

const res = await client.graphql("UserByScreenName", {
  variables: { screen_name: "elonmusk" },
});

console.log(res.data.user.result);

The first argument is Twitter's name for the query or mutation, which you can find in your browser's devtools. emusks ships a table of known operations with their query ids and feature flags, and throws graphql query <name> not found for names it doesn't know.

Option	Type	Description
variables	object	The operation's variables
fieldToggles	object	Field toggles, for operations that take them
body	object	Extra body fields, for POST operations
headers	object	Extra request headers

It returns the parsed JSON and throws as described in handling errors.

client.v1_1(endpoint, opts?)

The legacy REST API, still used for account management, media uploads, friendships, mutes, blocks and more.

const res = await client.v1_1("users/lookup", {
  params: { screen_name: "elonmusk" },
});

console.log(await res.json());

endpoint is a path from emusks' table, without the /1.1/ prefix or the .json suffix. A few endpoints exist for two methods and carry a prefix, such as get:account/settings and post:account/settings. You can also pass [method, url] for an endpoint that isn't in the table. Options are params (query parameters), body and headers.

It resolves to { status, headers, json(), text() } and throws when the body has an errors array.

client.v2(endpoint, opts?)

The v2 layer, used for adaptive search, explore settings, badge counts and a few other features.

const res = await client.v2("search/adaptive", {
  params: { q: "hello", count: 10 },
});

console.log(await res.json());

It takes the same params, body and headers options and resolves to the raw response, without checking for errors.