Read things in the graph
List the customers, projects and other things your organisation deals with, and read one thing's page, from the CLI, MCP or the TypeScript SDK.
Your Twin's graph holds the records synced from your organisation's connected systems. An entity is a type of record, such as an invoice or a contact. A thing is an individual record that has its own page in your Twin, such as a customer, a project, or a supplier. Your organisation's graph model decides which entity types have pages.
There are three read-only lookups:
- List the kinds of thing available, along with how many of each you can read.
- List the things of one kind by name.
- Read a single thing's full page: what it is, its record fields, what needs attention, its certified figures, what's connected to it across systems, its timeline, and its sources.
From the command line
Sign in with the Twin CLI first.
# The kinds, with each one's entity and count
twin graph things
# One kind's things, by name
twin graph things customer
# Narrowed by words of the name, by conditions on its fields, and read on from a later page
twin graph things customer --q "harbour" --where '[{"field":"status","op":"eq","value":"active"}]' --offset 50
# One thing, by its entity and the key the list gives
twin graph thing customer c-1042If a key has multiple parts, pass each part in order (for example,
twin graph thing stock_line WH1 A12). Add --json to any command to get the
full response, including the underlying rows and certificates behind each
figure.
The CLI output follows the same layout as a thing's page in the web app:
Customer: Harbour Supplies (entity customer, key c-1042)
In: xero, hubspot.
Opens in its own system: https://…
Its record, as the graph holds it:
- status: active
…
Needs attention:
- Outstanding: 2 in xero_invoice
Figures, each with its certificate:
…
Connected:
- xero_invoice: 46, newest 2026-10-11; these point at it, or at what it belongs to (customer ← xero_invoice)
Timeline, newest first (12):
- 2026-10-11 INV-0042 (xero_invoice)
Sources, with when each last synced: xero …; hubspot ….Fields keep their exact names and values, so you can pass them straight into a
list's --where filter or a twin graph query. Each connected group shows its
entity name, which is the name you use when querying it.
Through MCP
An assistant connected to your Twin over MCP has the same read-only lookups as
tools. The core tools are available on both the full endpoint (/mcp) and the
short graph endpoint (/mcp/graph):
twin_graph_thingslists available kinds of thing, or (when you passentity) lists the things of that kind by name. It acceptsq,where,limit, andoffsetjust like the CLI.twin_graph_thingreads a single thing's page byentityandkey, pulling together everything connected to it across your systems in one call.twin_graph_thing_history(full/mcpendpoint only) lists one thing's identity matches byentityandkey(see A thing's history).twin_graph_on_daylists what falls on a given day.twin_graph_thing_dated(full/mcpendpoint only) checks when a thing is next or was last dated.
When an assistant connects, it's guided to read a named customer, project, or
person's page with twin_graph_thing before writing custom queries, and to use
twin_graph_query when it needs figures across many records.
Each tool's text reply matches what the CLI prints, and its structured payload
matches the CLI's --json output.
With the TypeScript SDK
Set up the client as shown in the TypeScript SDK guide, then call:
const kinds = await twinClient.twinGraph.things();
const page = await twinClient.twinGraph.things({
entity: "customer",
q: "harbour",
where: [{ field: "status", op: "eq", value: "active" }],
offset: 50,
});
console.log(page.list?.total, page.list?.offset, page.list?.things.length);
const thing = await twinClient.twinGraph.thing({ entity: "customer", key: "c-1042" });
if (thing.found) console.log(thing.text);Who can read what
Things respect your permissions just like every other graph read. Entity types you can't access won't appear in the list, counts only include records you're allowed to read, and a thing outside your access comes back as not found. A missing thing and a restricted thing return the exact same response so nothing leaks.
A long list is never cut silently
Each list returns a single page of up to 200 things (50 by default unless you
pass a higher limit). The response always tells you how many matched and
which slice you're looking at (for example, customers 0–49 of 312 shown),
along with how to continue: call again with the next offset, or narrow the
results with q or where.
What falls on a day
When your organisation's graph model marks date fields on an entity (such as an invoice's due date), you can list everything falling on a given day in one call:
twin graph on-day 2026-11-13
twin graph on-day 2026-11-13 --entities invoice --limit 10 --jsonFor each marked date field, the response shows how many records you can read on
that day, their totals by currency (where the entity has an amount), and the
first few matching records with links back to their source systems. Date fields
match their own calendar day, while timestamps match their day in UTC. Over
MCP, use twin_graph_on_day; in the TypeScript SDK, call
twinClient.twinGraph.onDay({ day: "2026-11-13" }). Entities without a marked
date field aren't included, so an empty day can also mean no dates are marked
in your model yet.
When a thing is next or was last dated
A thing's dated records include both its own dates and the dates of records connected to it in your graph model, such as an artist's bookings or a customer's invoices. List the available dated series, then ask for the next record on or after a date, or the last one before it:
twin graph dated artist A-17
twin graph dated artist A-17 --of booking --field starts_on --next --jsonBy default, the reference day is today in UTC unless you pass --from. Dates
are matched the same way as in on-day. Only records your graph model actively
counts are included (for instance, cancelled bookings are skipped), and the
response tells you how many others were passed over; pass --all-classes to
include every record. You get back the matching record, its date, how many of
the thing's records fall on that day, a link to open it, and a certificate. Over
MCP, use twin_graph_thing_dated; in the TypeScript SDK, call
twinClient.twinGraph.thingDated(...). If you don't have access to a dated
series, it responds the same way as one that doesn't exist.
A thing's history
A thing's history is fetched separately from its main page so the page itself
stays fast. You can read it via twin graph history customer C-104,
twin_graph_thing_history over MCP,
GET /api/twin/graph/thing/history?entity=customer&key=C-104, or
twinClient.twinGraph.thingHistory({ entity: "customer", key: "C-104" }) in
the TypeScript SDK.
It returns up to 50 identity matches, newest first: records from other systems
that your Twin has identified as the same party. Each entry shows whether the
match was joined (automatically by rule or manually by a person), undone later,
or is still waiting for a decision, along with what fields were compared, the
model's match probability, and the proposal ID for undoing it
(twin.proposals.undo). You'll only see matches where you also have permission
to read the other record, and the more flag tells you if older matches
weren't included.
If you're an organisation admin viewing a shared organisation thing in the web app (not a personal mail or calendar item), the history response also includes page-view activity:
openedlists the 20 most recent views, newest first, showing each member's ID, their directory name (blank if they're no longer in the directory), the timestamp, and which surface (door) they used:web(the web app),native(Twin's desktop or mobile apps),gateway(the CLI or an external tool),agent(your Twin's own agent in a session), orother.openedCountsgives the total number of views and unique viewers over the last 30 days.
Requests made through the public gateway (the CLI, MCP clients, or Twin's
native apps), as well as tenant API keys and non-admin users, don't receive
opened or openedCounts. Viewing this history is itself logged as a single
read in the access record.