> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Session Graph Elements

Paginate elements in a graph session object. Elements are sorted by `created_at` by default; sorting switches to `updated_at` when `updated_since` is provided.

## **POST** `/revisions/:id/data/query` (Command: `list_session_graph_elements`)

### Request Body

| Parameter       | Type    | Required | Description                                                                                                                                      |
| :-------------- | :------ | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| `engine`        | string  | Yes      | Must be `workflow_blobhub`.                                                                                                                      |
| `command`       | string  | Yes      | Must be `list_session_graph_elements`.                                                                                                           |
| `session_id`    | string  | Yes      | The ID of the session that owns the graph envelope.                                                                                              |
| `alias`         | string  | Yes      | Alias of the graph session object.                                                                                                               |
| `type`          | string  | No       | Filter by element type: `"vertex"` or `"edge"`. Omit to return both.                                                                             |
| `ascending`     | boolean | No       | Sort direction. Default `false` (descending — most-recently-created or most-recently-updated first).                                             |
| `cursor`        | string  | No       | Opaque pagination cursor returned by a previous call.                                                                                            |
| `limit`         | integer | No       | Max elements per page, 1–1000 (out-of-range → 400). Default `10`.                                                                                |
| `updated_since` | string  | No       | Return only elements with `updated_at > updated_since` (ISO 8601). Useful for incremental delta syncs.                                           |
| `ids_only`      | boolean | No       | When `true`, returns lightweight `element_ids` objects (`element_id`, `type`, `rev`) instead of full element objects. Useful for reconciliation. |

**`updated_since`** — pass the timestamp of the last-known mutation to retrieve only elements added or
changed since that point. This is the recommended pattern for incremental client syncs after receiving
a `session_graph_changed` event.

**`ids_only`** — when you only need to know which elements exist (e.g. to reconcile a local cache),
set `ids_only: true`. The response switches from `elements` to `element_ids` (lightweight objects
with `element_id`, `type`, and `rev`) and is significantly smaller for large graphs.

### Response

When `ids_only` is `false` (default):

| Parameter  | Type            | Description                                                                                           |
| :--------- | :-------------- | :---------------------------------------------------------------------------------------------------- |
| `elements` | array of object | Page of graph elements. Sorted by `created_at` normally; by `updated_at` when `updated_since` is set. |
| `cursor`   | string or null  | Pagination cursor; `null` when this is the last page.                                                 |

When `ids_only` is `true`:

| Parameter     | Type            | Description                                                                               |
| :------------ | :-------------- | :---------------------------------------------------------------------------------------- |
| `element_ids` | array of object | Page of lightweight element records (`element_id`, `type`, `rev`) sorted by `created_at`. |
| `cursor`      | string or null  | Pagination cursor; `null` when this is the last page.                                     |

Page size is set by `limit` (default `10`, max `1000`). The opaque `cursor` + `limit` contract is shared by every
`list_*` command; pass the response `cursor` back verbatim until it is `null`.

### Errors

* `invalid_graph_envelope` — the alias does not exist or its `value.type` is not `"graph"`.
* `invalid_cursor` — the cursor is malformed or has expired.

### Example

<CodeGroup>
  ```json Request theme={null}
  {
    "engine": "workflow_blobhub",
    "command": "list_session_graph_elements",
    "session_id": "sess_001",
    "alias": "task_graph",
    "type": "vertex",
    "ascending": false,
    "updated_since": "2026-06-06T10:00:00.000000+00:00"
  }
  ```

  ```json Response theme={null}
  {
    "elements": [
      {
        "element_id": "task:1",
        "type": "vertex",
        "labels": ["task"],
        "props": { "title": "Research", "status": "in_progress" },
        "rev": 2,
        "created_at": "2026-06-06T10:00:00.000000+00:00",
        "updated_at": "2026-06-06T10:00:01.000000+00:00",
        "user_id": "usr_001"
      }
    ],
    "cursor": null
  }
  ```
</CodeGroup>

### See also

* [Graph session object](/blob-types/workflow/session-objects/graph/introduction) — envelope shape and element schema.
* [Apply Session Graph Mutations](/blob-types/workflow/operations/apply-session-graph-mutations) — write vertices and edges.
* [Query Session Graph](/blob-types/workflow/operations/query-session-graph) — traverse the graph with a query AST.
* [List Session Graph Neighbors](/blob-types/workflow/operations/list-session-graph-neighbors) — fetch neighbors of a set of vertices.
* [Get Session Graph Element](/blob-types/workflow/operations/get-session-graph-element) — fetch a single element by id.
* [Get Session Graph Elements](/blob-types/workflow/operations/get-session-graph-elements) — fetch multiple elements by id.
* [`session_graph_changed` event](/blob-types/workflow/workflows/session-events) — real-time delta; use `updated_since` to fetch the changed elements.