---
title: "Get Graph Operational Limits"
method: GET
path: "/v1/graphs/{graph_id}/limits"
tags: ["Graph Limits"]
---

# Get Graph Operational Limits

`GET /v1/graphs/{graph_id}/limits`

## 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}/limits`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Limits vary by subscription tier (ladybug-standard, ladybug-large, ladybug-xlarge). Includes storage, query, backup, rate, credit, document, and instance usage limits.

## Path parameters

- `graph_id` string, required

## Response `200`

Successful Response

- GraphLimitsResponse: Every operational limit that applies to a graph, and its usage.
  - `graph_id` string, required: Graph database identifier
  - `subscription_tier` string, required: Rate-limit tier enforced for requests to this graph
  - `graph_tier` string, required: Graph's database tier
  - `is_shared_repository` boolean, required: Whether this is a shared repository
  - `storage` StorageLimits: Storage limits information.
    - `current_usage_gb` number, nullable: Current storage usage in GB
    - `max_storage_gb` number, required: Instance storage cap in GB; ingest and materialize are refused above it
    - `approaching_limit` boolean, required: Whether approaching storage limit (>80%)
  - `queries` QueryLimits, required: Query operation limits.
    - `max_timeout_seconds` integer, required: Per-query time ceiling the graph engine enforces, in seconds
    - `chunk_size` integer, required: Default rows per streamed chunk (a request may set chunk_size, 10-10,000)
    - `max_rows_per_query` integer, required: Rows a non-streaming Cypher query returns before it stops (the response sets `truncated`); a streamed query returns up to 1,000,000
  - `copy_operations` CopyOperationLimits: File upload limits.
    - `max_file_size_gb` number, required: Maximum upload file size in GB
    - `supported_formats` string[], required: Supported file formats
  - `backups` BackupLimits: Backup operation limits.
    - `backup_retention_days` integer, required: Backup retention period in days
    - `max_backups_per_day` integer, required: Maximum user-initiated backups per day (-1 for unlimited)
    - `max_downloads_per_month` integer, nullable: Backup downloads allowed per user per calendar month (UTC)
  - `rate_limits` RateLimits, required: API rate limits.
    - `requests_per_minute` integer, required: Requests per minute limit
    - `requests_per_hour` integer, required: Requests per hour limit
    - `burst_capacity` integer, required: Burst capacity for short spikes
  - `credits` CreditLimits: AI credit limits (optional).
    - `monthly_ai_credits` integer, required: Monthly AI credits allocation
    - `current_balance` integer, required: Current credit balance
  - `documents` DocumentLimits: Knowledge-base document usage against the tier's cap.
    - `current_count` integer, required: Uploaded documents currently stored for this graph
    - `max_documents` integer, nullable: Maximum uploaded documents for this tier (null when uncapped)
    - `approaching_limit` boolean, required: Whether approaching document limit (>80%)
  - `subgraphs` SubgraphLimits: Subgraph count against the parent graph tier's cap. Subgraphs are refused at the tier cap regardless of how small they are, so this is a count axis independent of the storage one — `instance` already itemizes their footprint.
    - `current_count` integer, required: Subgraphs currently provisioned under this graph
    - `max_allowed` integer, nullable: Maximum subgraphs for this tier (null when uncapped)
    - `remaining` integer, nullable: Subgraphs that can still be created (null when uncapped)
    - `approaching_limit` boolean, required: Whether approaching subgraph limit (>80%)
  - `content` ContentLimits: Per-operation materialization limits.
    - `max_rows_per_copy` integer, required: Maximum rows per copy/materialization operation
    - `max_single_table_rows` integer, required: Maximum rows per staging table
    - `chunk_size_rows` integer, required: Rows per materialization chunk
  - `instance` InstanceUsage: Aggregate storage usage across the dedicated instance. Covers the parent graph, all subgraphs, DuckDB staging, and vector indexes.
    - `node_count` integer, nullable: Current node count (informational, no limit enforced)
    - `total_storage_gb` number, nullable: Total storage used across all databases in GB
    - `limit_gb` number, required: Instance storage cap in GB; ingest and materialize are refused above it
    - `usage_percentage` number, nullable: Storage usage as percentage of limit (e.g. 105.2). Derived from the enforced figure — durable bytes only, excluding `transient` build artifacts — so it can read lower than total_storage_gb/limit_gb while a blue-green rebuild is in flight.
    - `status` string, required: Instance status: 'healthy' (<80%), 'approaching' (80-100%), 'over_limit' (>100%)
    - `databases` DatabaseStorageEntry[]: Per-database storage breakdown
      - `graph_id` string, required: Database identifier
      - `is_parent` boolean: Whether this is the parent graph
      - `size_mb` number, nullable: Database size in MB
    - `items` StorageItem[]: Itemized storage by type — graph, memory, subgraph, vectors, staging, transient, orphan. Sums to total_storage_gb. Only `subgraph` items correspond to live subgraphs, so this is the type to sum when reconciling against the subgraph list.
      - `type` string, required: One of: graph, memory, subgraph, vectors, staging, transient (blue-green build artifact), orphan (a `{parent}_*` database, vector index, or staging file with no row in the graph registry — leftover of a deleted subgraph). Transient and orphan items are collected by the platform's daily storage-reclaim job.
      - `id` string, required: Database or index identifier
      - `bytes` integer, required: Size in bytes

## Other responses

- `400`: Invalid request
- `401`: Authentication required
- `403`: Access denied
- `404`: Resource not found
- `422`: Validation Error
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[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/28ffd375c457?raw)