Usage

Use the Phase API to read analytics reports from your own scripts, dashboards, and backend services.

Get your API key

1. Sign in to Phase Dashboard.
2. Create a new project or select an existing one.
3. Open Application → API Keys.
4. Copy your API key. Keys for this API start with phase_public_.
5. Copy the App ID from the same screen. You need it in every request path.

Base URL

https://api.phase.sh/public-api/v1

First request

curl "https://api.phase.sh/public-api/v1/apps/<app_id>/reports/events/overview" \
  -H "Authorization: Bearer phase_public_your_key"

const response = await fetch(
  'https://api.phase.sh/public-api/v1/apps/<app_id>/reports/events/overview',
  {
    headers: {
      Authorization: 'Bearer phase_public_your_key',
    },
  }
);

if (!response.ok) {
  throw new Error(`Request failed with ${response.status}`);
}

const data = await response.json();
console.log(data);

Example response

{
  "totalEvents": 216,
  "events24h": 0,
  "totalEventsChange24h": 0,
  "events24hChange": 0,
  "meta": {
    "generatedAt": "2026-04-06T15:02:52.814Z",
    "consistency": "eventual",
    "identityModel": "user"
  }
}

Request format

Path parameter

• appId
  • Type: string
  • Required: yes
  • Value: the App ID shown in Application → API Keys

Header

• Authorization
  • Type: string
  • Required: yes
  • Format: Bearer phase_public_your_key
  • Value: your API key

Query parameters

• startDate

  • Type: string
  • Required: no
  • Format: ISO 8601 timestamp
  • Example: 2026-01-15T00:00:00.000Z
  • Used by: timeseries endpoints and date-filtered breakdown endpoints

• endDate

  • Type: string
  • Required: no
  • Format: ISO 8601 timestamp
  • Example: 2026-02-15T23:59:59.999Z
  • Used by: timeseries endpoints and date-filtered breakdown endpoints

• metric

  • Type: string
  • Required: no
  • Used by: timeseries endpoints
  • Allowed values depend on the endpoint:
    • Sessions: sessionCount, avgSessionDuration, bounceRate
    • Users: activeUsers, totalUsers, newUsers

• dimension

  • Type: string
  • Required: no
  • Used by: breakdown endpoints
  • Allowed values depend on the endpoint:
    • Events: eventName, screenName
    • Sessions: platform, country, city
    • Users: platform, country, city

• limit

  • Type: number
  • Required: no
  • Used by: breakdown endpoints
  • Range: 1 to 50
  • Default: 10

Events

Use event reports for headline counts, daily trends, and top events or screens.

Endpoints

• GET /apps/:appId/reports/events/overview

  • Returns total events, 24h events, and change values.

• GET /apps/:appId/reports/events/timeseries

  • Returns daily event counts.
  • Supports startDate and endDate.

• GET /apps/:appId/reports/events/breakdown

  • Returns event counts grouped by eventName or screenName.
  • Supports dimension, startDate, endDate, and limit.

Example: event breakdown

curl "https://api.phase.sh/public-api/v1/apps/<app_id>/reports/events/breakdown?dimension=eventName&startDate=2026-01-15T00:00:00.000Z&endDate=2026-02-15T23:59:59.999Z&limit=10" \
  -H "Authorization: Bearer phase_public_your_key"

const params = new URLSearchParams({
  dimension: 'eventName',
  startDate: '2026-01-15T00:00:00.000Z',
  endDate: '2026-02-15T23:59:59.999Z',
  limit: '10',
});

const response = await fetch(
  `https://api.phase.sh/public-api/v1/apps/<app_id>/reports/events/breakdown?${params}`,
  {
    headers: {
      Authorization: 'Bearer phase_public_your_key',
    },
  }
);

const data = await response.json();

Sessions

Use session reports for totals, duration, bounce rate, and session distribution by platform or location.

Endpoints

• GET /apps/:appId/reports/sessions/overview

  • Returns total sessions, active sessions, average session duration, and bounce rate.

• GET /apps/:appId/reports/sessions/timeseries

  • Returns daily session metrics.
  • Supported metric values: sessionCount, avgSessionDuration, bounceRate.
  • Supports startDate, endDate, and metric.

• GET /apps/:appId/reports/sessions/breakdown

  • Returns session counts grouped by platform, country, or city.
  • Supports dimension, startDate, endDate, and limit.

Example: session timeseries

curl "https://api.phase.sh/public-api/v1/apps/<app_id>/reports/sessions/timeseries?metric=sessionCount&startDate=2026-01-15T00:00:00.000Z&endDate=2026-02-15T23:59:59.999Z" \
  -H "Authorization: Bearer phase_public_your_key"

const params = new URLSearchParams({
  metric: 'sessionCount',
  startDate: '2026-01-15T00:00:00.000Z',
  endDate: '2026-02-15T23:59:59.999Z',
});

const response = await fetch(
  `https://api.phase.sh/public-api/v1/apps/<app_id>/reports/sessions/timeseries?${params}`,
  {
    headers: {
      Authorization: 'Bearer phase_public_your_key',
    },
  }
);

const data = await response.json();

Users

Use user reports for totals, active users, new users, and user distribution by platform or location.

Endpoints

• GET /apps/:appId/reports/users/overview

  • Returns total users, active users, new users, and summary breakdowns.

• GET /apps/:appId/reports/users/timeseries

  • Returns daily user metrics.
  • Supported metric values: activeUsers, totalUsers, newUsers.
  • Supports startDate, endDate, and metric.

• GET /apps/:appId/reports/users/breakdown

  • Returns user counts grouped by platform, country, or city.
  • Supports dimension and limit.

Example: user overview

curl "https://api.phase.sh/public-api/v1/apps/<app_id>/reports/users/overview" \
  -H "Authorization: Bearer phase_public_your_key"

const response = await fetch(
  'https://api.phase.sh/public-api/v1/apps/<app_id>/reports/users/overview',
  {
    headers: {
      Authorization: 'Bearer phase_public_your_key',
    },
  }
);

const data = await response.json();

Response metadata

Every report response includes a meta object.

• generatedAt is the server-side timestamp for the response.
• consistency is currently eventual.
• identityModel is currently user.

Security guidance