Developer

Embed analytics in your app

Embed Umami analytics in your own application with an iframe share URL, direct calls to the Umami API, or the Umami API client.

Use Umami's share URLs and API to embed analytics dashboards or data directly into your own application, internal tools, or client portals.

The simplest approach is to create a share URL and embed it in an iframe.

Navigate to your website in Umami.
Click Edit on the website.
Go to the Share URL section and create a new share.
Copy the generated URL.

Embed in your app#

<iframe
  src="https://your-umami.example.com/share/abc123/My-Website"
  style="width: 100%; height: 800px; border: none;"
  loading="lazy"
  title="Analytics dashboard"
></iframe>

For this to work, you may need to configure the ALLOWED_FRAME_URLS environment variable on your Umami instance to allow your app's domain:

ALLOWED_FRAME_URLS="https://your-app.example.com"

ALLOWED_FRAME_URLS is a build-time variable, so you need to rebuild Umami after setting it. See Environment variables.

Option 2: Use the API to build custom dashboards#

For full control over the presentation, use the Umami API to fetch data and render it in your own UI.

Authentication#

For self-hosted instances, get a token:

const response = await fetch('https://your-umami.example.com/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: 'admin', password: 'your-password' }),
});
const { token } = await response.json();

Use the token in the Authorization header:

const headers = { Authorization: `Bearer ${token}` };

For Umami Cloud, use your API key as the Bearer credential instead:

const apiKey = 'your-api-key';
const headers = { Authorization: `Bearer ${apiKey}` };

Fetch website stats#

const stats = await fetch(
  `https://your-umami.example.com/api/websites/${websiteId}/stats?startAt=${startAt}&endAt=${endAt}`,
  { headers }
).then(r => r.json());

// stats = { pageviews, visitors, visits, bounces, totaltime }

Fetch page view time series#

const pageviews = await fetch(
  `https://your-umami.example.com/api/websites/${websiteId}/pageviews?startAt=${startAt}&endAt=${endAt}&unit=day`,
  { headers }
).then(r => r.json());

Render with any charting library#

Use the returned data with Chart.js, Recharts, D3, or any visualization library:

import { BarChart, Bar, XAxis, YAxis } from 'recharts';

function PageviewsChart({ data }) {
  return (
    <BarChart data={data.pageviews}>
      <XAxis dataKey="x" />
      <YAxis />
      <Bar dataKey="y" fill="#8884d8" />
    </BarChart>
  );
}

Option 3: Use the API client#

The Umami API client simplifies authentication and provides typed methods:

import { getClient } from '@umami/api-client';

// Configure via environment variables:
//   UMAMI_API_CLIENT_USER_ID
//   UMAMI_API_CLIENT_SECRET
//   UMAMI_API_CLIENT_ENDPOINT
// or, for Umami Cloud:
//   UMAMI_API_KEY
//   UMAMI_API_CLIENT_ENDPOINT=https://api.umami.is/v1
const client = getClient();

// Methods return { ok, data, status, error }
const { data } = await client.getWebsiteStats(websiteId, {
  startAt: Date.now() - 86400000,
  endAt: Date.now(),
});

See the API reference for all available endpoints.

PreviousSet up A/B testing with tags NextSend server-side events