Service behavior and operational expectations

Production integrations need boundaries, not adjectives such as “real-time” or “scalable.” This page states the currently documented behavior and identifies where GraphJSON does not publish a formal guarantee.

At a glance#

The public request guardrail is the integration limit to design against. Internal load-test results do not override it.

What a successful ingestion response means#

For the single and bulk logging endpoints, a 2xx response means GraphJSON accepted the request through the documented endpoint.

It does not prove:

• a producer sent every intended business event
• a retry did not create a duplicate
• the payload follows your tracking plan
• the event will appear in a particular customer workflow within a contractual number of seconds
• the event is safe to use as an authoritative billing or entitlement record

For important events, keep a stable event_id, retain failed jobs, and reconcile GraphJSON against the source system. See Reliable event delivery.

Freshness#

Events ordinarily become available for exploration as they arrive; GraphJSON does not require a daily ETL rebuild before a new JSON field can be queried.

GraphJSON does not currently publish a guaranteed maximum ingestion-to-query delay. Design UI and operations accordingly:

• show a “last updated” or reporting-window label where freshness matters
• do not block a customer transaction on a GraphJSON query
• distinguish empty data from unavailable data
• keep the source system authoritative
• monitor your own queue age and delivery failures

If a successfully accepted event remains absent:

1. confirm the workspace, collection, timestamp, and time zone
2. widen the time range
3. inspect Samples
4. check retention
5. record the approximate request time and redacted response
6. follow Troubleshoot missing data

Rate limits and throughput#

The ingestion guardrail is 40 requests per second per workspace.

Use the bulk endpoint to send up to 50 events in one request. At the request guardrail, full batches represent up to 2,000 submitted events per second, but this arithmetic is not a throughput guarantee. Payload size, burst shape, retries, and workload characteristics still matter.

When planning sustained or unusually bursty traffic, contact hi@graphjson.com with:

• average and peak events per second
• average serialized event size
• peak duration
• number of collections
• retry and queue design
• required freshness
• expected query and embed traffic

GraphJSON has performed higher internal load tests, but customers should not design above the published guardrail without an agreed capacity plan.

Backoff and overload#

On 429, retry with exponential backoff and jitter. On network failures and 500, retry a bounded number of times. Do not retry an unchanged 400.

When the sender is overloaded:

• bound concurrency
• preserve original occurrence timestamps
• batch compatible events
• monitor queue depth and oldest-event age
• isolate permanently invalid events
• never drop important events silently

See Errors and limits for the status matrix.

Query behavior#

SQL queries are read-only and receive an outer 2,000-row limit. The SQL notebook runs queries as jobs and waits for up to 15 minutes.

Interactive analytics should normally return well before that maximum. A query approaching the maximum should be narrowed or redesigned.

GraphJSON may throttle sustained, unusually high rates of unique or computationally expensive read queries to protect the service. Repeated views of the same embedded configuration benefit from caching; generating many unique configurations defeats that reuse.

Use SQL performance and troubleshooting before turning a heavy notebook into a high-traffic customer feature.

Embed caching#

Embedded graphs use a 15-minute cache TTL by default.

Implications:

• repeated views of the same graph do not necessarily execute a new database query
• a newly accepted event may not appear in an existing embed immediately
• a full-screen dashboard reload does not bypass the embed cache policy
• personalized configurations need cache keys that include every authorized tenant-specific input

If a use case needs a different freshness policy, contact GraphJSON before launch. Do not add random query parameters merely to bypass caching; that can create unnecessary load and still does not establish a supported freshness contract.

Availability and failure handling#

GraphJSON does not currently publish a customer availability SLA or automated public status feed. See Service status and incident communication for the present reporting and recovery path.

Build integrations so an analytics outage does not break the product:

business transaction
  ├─ commit authoritative state
  ├─ make analytics event durable
  └─ return the product response

background delivery
  ├─ send a bounded batch
  ├─ retry recoverable failures
  └─ alert on queue age or dead letters

For embedded analytics:

• reserve chart space while loading
• show an unavailable state distinct from an empty result
• provide a retry
• avoid retry storms
• keep core account actions usable

Backups and recovery#

GraphJSON maintains service backups for infrastructure recovery.

No public recovery-time objective or recovery-point objective is currently published, and customers cannot select and restore an arbitrary snapshot. Service backups are not an undo feature for collection deletion and should not be your only archival system.

Keep authoritative records and required archives in systems you control. See Export, delete, and move your data.

Maintenance and changes#

GraphJSON may update infrastructure and dependencies as part of operating the service. Documented API compatibility expectations are in API compatibility and changelog.

Clients should:

• tolerate additional response fields
• avoid depending on exact human-readable error text
• branch on HTTP status
• set explicit timeouts
• log redacted request metadata
• review the changelog before changing an integration

When to contact support#

For an ingestion or query incident, send:

• approximate time and time zone
• endpoint
• collection
• HTTP status
• redacted error body
• application-level event ID
• whether retries succeeded
• scope: one request, one producer, or the workspace

Never send:

• API keys
• passwords or session tokens
• complete private payloads
• public embed URLs containing sensitive configurations

Email hi@graphjson.com.