Custom dashboard

This example builds a dashboard in Next.js that shows one count card and one chart. A Next.js route on the server holds the API key and calls the Query API. The browser polls that route at an interval that stays inside the rate limit of the workspace. The Query API needs the Starter plan or higher and an API key with the Query API permission. Read Query API.

Files

File	Holds
`lib/grain-api.ts`	The API client. It runs on the server only.
`app/api/metrics/route.ts`	The Next.js route that holds the key and caches the result.
`components/CountCard.tsx`	The count card.
`components/EventsChart.tsx`	The chart of events per day.
`app/dashboard/page.tsx`	The page that polls the route.

Create the project and install the chart library.

npx create-next-app@latest grain-dashboard --typescript --tailwind --eslint
cd grain-dashboard
npm install chart.js react-chartjs-2

Put the tenant alias and the API key in .env.local. Do not add a NEXT_PUBLIC_ prefix to the key. A NEXT_PUBLIC_ variable is compiled into the browser bundle.

GRAIN_TENANT_ID=your-tenant-id
GRAIN_API_KEY=$GRAIN_API_KEY

The API client

The client wraps the three endpoints. On a status code other than 2xx, it throws a GrainApiError that carries the status code and the Retry-After value.

// lib/grain-api.ts
const BASE_URL = 'https://queryapis.grainql.com/v1/api/query';

export interface QueryRequest {
  event?: string;
  after?: string;
  before?: string;
  filterSet?: Array<{ property: string; comparison: string; value: unknown }>;
  pagination?: { offset: number; size: number };
}

export interface GrainEvent {
  eventName: string;
  userId: string;
  eventTs: string;
  properties: Record<string, unknown>;
  eventDate: string;
  insertId: string;
}

export class GrainApiError extends Error {
  constructor(public status: number, message: string, public retryAfter?: number) {
    super(message);
  }
}

async function send<T>(path: string, init: RequestInit): Promise<T> {
  const response = await fetch(`${BASE_URL}${path}`, init);
  if (!response.ok) {
    const retryAfter = Number(response.headers.get('Retry-After')) || undefined;
    const body = await response.json().catch(() => ({ error: response.statusText }));
    throw new GrainApiError(response.status, body.error, retryAfter);
  }
  return response.json();
}

export function createGrainApi(apiKey: string, tenantId: string) {
  const headers = { 'Content-Type': 'application/json', 'X-API-Key': apiKey };
  return {
    queryEvents: (request: QueryRequest) =>
      send<GrainEvent[]>(`/${tenantId}`, {
        method: 'POST',
        headers,
        body: JSON.stringify(request),
      }),
    countEvents: (request: Omit<QueryRequest, 'pagination'>) =>
      send<{ count: number }>(`/count/${tenantId}`, {
        method: 'POST',
        headers,
        body: JSON.stringify(request),
      }).then((result) => result.count),
    listEventNames: () => send<string[]>(`/events/${tenantId}`, { headers }),
  };
}

export const grainApi = createGrainApi(process.env.GRAIN_API_KEY!, process.env.GRAIN_TENANT_ID!);

The route

The route makes two Query API calls per refresh: one count and one query of up to 1,000 events. It keeps the last result in memory for CACHE_MS milliseconds. Every browser that opens the dashboard inside that window gets the cached result, so the number of viewers does not change the number of Query API calls.

// app/api/metrics/route.ts
import { NextResponse } from 'next/server';
import { grainApi, GrainApiError } from '@/lib/grain-api';

const CACHE_MS = Number(process.env.DASHBOARD_REFRESH_SECONDS ?? 900) * 1000;

let cache: { at: number; body: unknown } | null = null;

function isoDate(daysAgo: number) {
  const date = new Date();
  date.setUTCDate(date.getUTCDate() - daysAgo);
  return date.toISOString().slice(0, 10);
}

export async function GET() {
  if (cache && Date.now() - cache.at < CACHE_MS) {
    return NextResponse.json(cache.body);
  }

  const range = { after: isoDate(30), before: isoDate(0) };

  try {
    const [count, events] = await Promise.all([
      grainApi.countEvents(range),
      grainApi.queryEvents({ ...range, pagination: { offset: 0, size: 1000 } }),
    ]);
    cache = { at: Date.now(), body: { count, events, range } };
    return NextResponse.json(cache.body);
  } catch (error) {
    if (error instanceof GrainApiError) {
      const headers = error.retryAfter ? { 'Retry-After': String(error.retryAfter) } : undefined;
      return NextResponse.json({ error: error.message }, { status: error.status, headers });
    }
    return NextResponse.json({ error: 'Query API request failed' }, { status: 502 });
  }
}

A request to the route returns the count, the events, and the range.

curl http://localhost:3000/api/metrics

{
  "count": 15247,
  "events": [
    {
      "eventName": "page_viewed",
      "userId": "user_123",
      "eventTs": "2024-01-15T10:30:00Z",
      "properties": { "page": "/home", "referrer": "https://google.com" },
      "eventDate": "2024-01-15",
      "insertId": "unique-event-id"
    }
  ],
  "range": { "after": "2023-12-16", "before": "2024-01-15" }
}

The count card

// components/CountCard.tsx
export function CountCard({ title, value }: { title: string; value: number | null }) {
  return (
    <div className="rounded-lg bg-white p-6 shadow">
      <p className="text-sm text-gray-600">{title}</p>
      <p className="text-2xl font-bold text-gray-900">
        {value === null ? '...' : value.toLocaleString()}
      </p>
    </div>
  );
}

The chart

The chart groups the events by eventDate and shows one point per day of the range.

// components/EventsChart.tsx
import { Line } from 'react-chartjs-2';
import { Chart, CategoryScale, LinearScale, PointElement, LineElement } from 'chart.js';
import type { GrainEvent } from '@/lib/grain-api';

Chart.register(CategoryScale, LinearScale, PointElement, LineElement);

export function EventsChart({ events }: { events: GrainEvent[] }) {
  const perDay = new Map<string, number>();
  for (const event of events) {
    perDay.set(event.eventDate, (perDay.get(event.eventDate) ?? 0) + 1);
  }
  const labels = [...perDay.keys()].sort();

  return (
    <div className="rounded-lg bg-white p-6 shadow">
      <h2 className="mb-4 text-lg font-medium text-gray-900">Events per day</h2>
      <Line
        data={{
          labels,
          datasets: [{ label: 'Events', data: labels.map((day) => perDay.get(day) ?? 0) }],
        }}
        options={{ responsive: true, scales: { y: { beginAtZero: true } } }}
      />
    </div>
  );
}

The page

The page polls /api/metrics. If the route answers 429, the page waits for the number of seconds in Retry-After before the next poll. The poll interval and the route cache use the same number, so a poll inside the cache window costs no Query API call.

// app/dashboard/page.tsx
'use client';

import { useEffect, useState } from 'react';
import { CountCard } from '@/components/CountCard';
import { EventsChart } from '@/components/EventsChart';
import type { GrainEvent } from '@/lib/grain-api';

const REFRESH_MS = Number(process.env.NEXT_PUBLIC_DASHBOARD_REFRESH_SECONDS ?? 900) * 1000;

interface Metrics {
  count: number;
  events: GrainEvent[];
  range: { after: string; before: string };
}

export default function Dashboard() {
  const [metrics, setMetrics] = useState<Metrics | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    let timer: ReturnType<typeof setTimeout>;

    async function poll() {
      const response = await fetch('/api/metrics');
      let delay = REFRESH_MS;
      if (response.status === 429) {
        const retryAfter = Number(response.headers.get('Retry-After'));
        delay = retryAfter > 0 ? retryAfter * 1000 : REFRESH_MS;
        setError(`Rate limit reached. Next refresh in ${delay / 1000} seconds.`);
      } else if (!response.ok) {
        setError((await response.json()).error ?? `Request failed with ${response.status}`);
      } else {
        setMetrics(await response.json());
        setError(null);
      }
      timer = setTimeout(poll, delay);
    }

    poll();
    return () => clearTimeout(timer);
  }, []);

  return (
    <main className="mx-auto max-w-5xl space-y-6 p-8">
      {error && <p className="text-red-600">{error}</p>}
      <CountCard title="Events, last 30 days" value={metrics?.count ?? null} />
      <EventsChart events={metrics?.events ?? []} />
    </main>
  );
}

The poll interval

The rate limit counts per workspace, not per viewer: 120 requests per minute, on every plan. One refresh of this dashboard costs 2 Query API requests, so the limit permits a refresh every second. The route cache decides the real cost. The default of 900 seconds costs 192 requests a day and leaves the limit free for other clients of the workspace. Set NEXT_PUBLIC_DASHBOARD_REFRESH_SECONDS to the same value, so the browser does not poll more often than the cache refreshes. A refresh that a user triggers by hand costs the same 2 requests and must count against the same budget.

Errors

Status	Body	What to do
`401`	`{"error":"Missing X-API-Key header"}` or `{"error":"Invalid API key or insufficient permissions"}`	Make sure that `GRAIN_API_KEY` is set on the server and that the key has the Query API permission.
`403`	`{"error":"Query API requires Starter plan or higher. ..."}`	Choose a plan for the workspace. The route cannot recover.
`404`	`{"error":"Tenant not found"}`	Use the tenant alias from the dashboard in `GRAIN_TENANT_ID`, not the UUID.
`429`	`{"error":"rate_limit_exceeded", ...}` with `Retry-After`	Wait `Retry-After` seconds. The page above does this. Then increase the interval.
`502` from the route	`{"error":"Query API request failed"}`	A network error between your server and the Query API. Retry on the next poll.

Limits

Limit	Value	Where
Events per query	1,000	`pagination.size`. The chart reads at most 1,000 events per refresh.
Requests per minute	120	Per workspace, on every plan. Every key of the workspace shares it.
Route cache	`DASHBOARD_REFRESH_SECONDS`	One process. Each server instance keeps its own cache.

Deployment

Run npm run build, then deploy with vercel.
Set GRAIN_TENANT_ID, GRAIN_API_KEY, DASHBOARD_REFRESH_SECONDS, and NEXT_PUBLIC_DASHBOARD_REFRESH_SECONDS in the environment of the host.
If the host runs more than one instance, each instance holds its own cache and makes its own requests. Move the cache to a shared store when many instances run.
Put the dashboard behind your own authentication. The route answers any caller.

Read Data export for a script that pages through every event. Read Filters for the filterSet operators.

​Files

​The API client

​The route

​The count card

​The chart

​The page

​The poll interval

​Errors

​Limits

​Deployment