Quickstart | GraphJSON Docs

This quickstart takes you through the smallest complete GraphJSON workflow: create a collection, send one event, verify it, and build a chart.

Before you begin#

You need a GraphJSON account and a server-side environment where you can make an HTTPS request. The example uses Node.js 18 or newer, which includes fetch.

Security: Your GraphJSON API key can read and write workspace data. Keep it on the server, store it in an environment variable, and never commit it to source control or expose it in browser JavaScript.

1. Create a collection#

Open Collections, select New Collection, and use:

Name: product_events
Description: Product behavior used for activation and conversion metrics
Retention: Store indefinitely for this quickstart

After you create it, GraphJSON opens the collection page.

2. Copy your API key#

Open the collection’s Logging tab. The generated examples already contain the API key and collection name you need.

For local development, put the key in your environment:

export GRAPHJSON_API_KEY="your_api_key"

3. Send an event#

Create send-event.mjs:

const event = {
  event: "checkout_completed",
  user_id: "usr_42",
  plan: "pro",
  amount: 4900,
  currency: "usd"
};

const response = await fetch("https://api.graphjson.com/api/log", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: process.env.GRAPHJSON_API_KEY,
    collection: "product_events",
    timestamp: Math.floor(Date.now() / 1000),
    json: JSON.stringify(event)
  })
});

const body = await response.json();

if (!response.ok) {
  throw new Error(body.error || `GraphJSON returned ${response.status}`);
}

console.log(body);

Run it:

node send-event.mjs

The outer request body is JSON, and its json field is a serialized JSON string. That double serialization is intentional.

4. Verify the event#

Return to the Logging tab and select Verify logs. When GraphJSON finds the event, it opens the visualizer.

If verification does not find it:

Confirm that the request returned a 2xx status.
Confirm that collection is exactly product_events.
Confirm that timestamp is an integer in Unix seconds, not milliseconds.
Open Samples, set the range to 7 days ago → now, and remove any filters.

See Troubleshoot missing data for a complete checklist.

5. Build a chart#

In the Visualize tab:

Choose Single Line.
Keep Count as the aggregation.
Set the time range to 7 days ago → now.
Add the filter event = checkout_completed.
Select Visualize.

You now have a time series of completed checkouts. With one event, the chart is intentionally simple; send a few events with different timestamps to make the trend visible.

6. Save or embed it#

Select Export:

To Dashboard saves the chart to a GraphJSON dashboard.
As static iframe gives you a ready-to-use chart URL.
As embed API call lets your server generate a chart for dynamic filters.
As data API call returns the chart’s data as JSON.
As Alert is available for single-line visualizations.

Next steps#

Learn the event data model.
Add production-grade logging and retries.
Batch high-volume events with bulk logging.
Learn every visualizer control.