---
title: "Execute Cypher Statement"
method: POST
path: "/v1/graphs/{graph_id}/query/cypher"
tags: ["Query"]
---

# Execute Cypher Statement

`POST /v1/graphs/{graph_id}/query/cypher`

## Request

- Base URL: `https://api.robosystems.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.robosystems.ai/v1/graphs/{graph_id}/query/cypher`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Cypher over the graph (LadybugDB). Main graphs are **read-only** — use the staging pipeline to ingest data. Subgraphs support full writes. Always use parameterized queries (`parameters: {"key": "val"}`) to prevent injection. Response modes: `auto` (default), `sync`, `async`, `stream`. Under load, queries are queued and emit an `operation_id` for SSE monitoring at `/v1/operations/{id}/stream`.

## Path parameters

- `graph_id` string, required

## Query parameters

- `mode` 'auto' | 'sync' | 'async' | 'stream': Response modes for execution.
- `chunk_size` integer, nullable: Rows per chunk for streaming
- `test_mode` boolean: Enable test mode for better debugging

## Request body

- CypherStatementRequest: Request model for Cypher query execution.
  - `query` string, required: The Cypher query to execute. Use parameters ($param_name) for all dynamic values to prevent injection attacks.
  - `parameters` object, nullable: Query parameters for safe value substitution. ALWAYS use parameters instead of string interpolation.
  - `timeout` integer, nullable: Query timeout in seconds (1-300)

## Response `200`

Successful Response

- unknown

## Other responses

- `202`: Query queued — monitor via SSE at /v1/operations/{operation_id}/stream
- `400`: Invalid request
- `401`: Authentication required
- `403`: Access denied
- `404`: Resource not found
- `408`: Query timeout
- `422`: Validation Error
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: Service unavailable

---

[API](https://skmtc.dev/robosystems/apis/robosystems-api.md) · [All operations](https://skmtc.dev/robosystems/apis/robosystems-api/llms.txt) · [OpenAPI document](https://skmtc.dev/robosystems/apis/robosystems-api/revisions/e661e2d5ca6a?raw)