Execute Cypher Statement

post/v1/graphs/{graph_id}/query/cypher

Part of Query.

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.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id

Query parameters

Name	Type	Description
`mode`optional	ResponseMode	Response mode override One of: `auto`, `sync`, `async`, `stream`
`chunk_size`optional	integer	Rows per chunk for streaming Constraints: 10–10000
`test_mode`optional	boolean	Enable test mode for better debugging Default: `false`

Request body

Required, application/json.

Field Type Description

Field	Type	Description
`query`required	string	The Cypher query to execute. Use parameters ($param_name) for all dynamic values to prevent injection attacks. Constraints: 1–50000 characters
`parameters`optional	object	Query parameters for safe value substitution. ALWAYS use parameters instead of string interpolation.
`timeout`optional	integer	Query timeout in seconds (1-300) Default: `60` Constraints: 1–300

queryrequired

string

The Cypher query to execute. Use parameters ($param_name) for all dynamic values to prevent injection attacks.

Constraints: 1–50000 characters

parametersoptional

object

Query parameters for safe value substitution. ALWAYS use parameters instead of string interpolation.

timeoutoptional

integer

Query timeout in seconds (1-300)

Default: 60

Constraints: 1–300

Example request

curl · example 1 of 5

curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/query/cypher" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "parameters": {
    "entity_type": "Company",
    "limit": 100
  },
  "query": "MATCH (n:Entity {type: $entity_type}) RETURN n LIMIT $limit",
  "timeout": 60
}'

curl · example 2 of 5

curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/query/cypher" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "parameters": {
    "entity_name": "Acme Corp",
    "limit": 50,
    "min_amount": 1000
  },
  "query": "MATCH (e:Entity)-[r:TRANSACTION]->(t:Entity) WHERE r.amount >= $min_amount AND e.name = $entity_name RETURN e, r, t LIMIT $limit",
  "timeout": 120
}'

curl · example 3 of 5

curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/query/cypher" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "parameters": {
    "identifier": "ENT123456"
  },
  "query": "MATCH (n:Entity) WHERE n.identifier = $identifier RETURN n",
  "timeout": 30
}'

curl · example 4 of 5

curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/query/cypher" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "parameters": {
    "form": "10-K",
    "limit": 20
  },
  "query": "MATCH (c:Company)-[:FILED]->(f:Filing) WHERE f.form_type = $form RETURN c.ticker, c.name, COUNT(f) as filing_count ORDER BY filing_count DESC LIMIT $limit",
  "timeout": 60
}'

curl · example 5 of 5

curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/query/cypher" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "MATCH (n) RETURN n LIMIT 10",
  "timeout": 30
}'

Responses

200 Successful Response

Response

"string"

Status	Meaning
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