Eas Observe

EAS Observe CLI

EAS Observe collects app performance telemetry and custom events from Expo apps and exposes them through the eas observe:* commands. The CLI changes between releases, so treat --help as the source of truth: run eas observe --help to list the commands the installed CLI has, and eas observe:<command> --help for a command's current flags.

Source: https://docs.expo.dev/eas/observe/eas-cli/ — the canonical CLI page. This reference adds table layouts, JSON output shapes, and pagination details that the docs page does not cover.

Commands Overview

All commands take these flags:

• --project-id <id> — run against a specific project without needing a project directory. When passed, the command will not try to create a new EAS project where one is unneeded.

• --json — machine-readable output (implies --non-interactive)

• --non-interactive — fail instead of prompting

All commands except observe:event also take these flags:

• --start <ISO date> and --end <ISO date> — explicit time range

• --days <N> — show data from the last N days (mutually exclusive with --start/--end, minimum 1)

• --environment <name> — filter by environment, for example production or development

--platform <android|ios|ipados|macos|tvos|apple> (default: all) is on every command except observe:session and observe:event, which are scoped to one session or one event already. apple covers iOS, iPadOS, tvOS, and macOS.

Default time range is the last 60 days when none of --days, --start, --end is given.

Plan gating. Observe is a paid feature, and the server rejects queries the account's plan does not include (EAS_OBSERVE_PLAN_UPGRADE_REQUIRED or EAS_OBSERVE_FEATURE_NOT_AVAILABLE_IN_FREE_TIER). The CLI surfaces the server's upgrade message, which links to the account's billing page. Session timelines in particular are checked before the interactive picker runs. A plan-gate failure is not a bug in the command or its flags.

Expo MCP Server tools

Source: https://docs.expo.dev/eas/observe/mcp/

The Expo MCP Server has read-only tools that return the same data as the CLI. When the observe_* tools are available, use them instead of the CLI: they use the Expo account that the MCP client signed in with, so they need no EAS CLI install and no access token. The queries, metric names, and workflows in this file apply to both.

Differences from the CLI:

• No error-group tools. For error groups and stack traces, use eas observe:errors and eas observe:event. observe_session includes the errors of one session. An empty result from the other MCP tools does not mean that the app has no errors.

• Project: pass appId or appFullName (such as @owner/my-app). In a project directory, read the project ID from the app config.

• Platform: platform takes ANDROID, IOS, IPADOS, MACOS, or TVOS. There is no apple value. As in the CLI, observe_versions, observe_metrics_summary, and observe_routes return separate Android and iOS results without platform, and observe_metrics, observe_event_names, and observe_events return results from all platforms.

• Environment: only observe_event_names and observe_events take environment. observe_versions, observe_metrics_summary, observe_metrics, and observe_routes have no environment input, unlike the CLI's --environment flag.

• Time range: days (up to 365), or start and end. The default is the last 60 days. start and end must be ISO 8601 date-times with a timezone, such as 2026-10-01T00:00:00Z. A date-only value fails. Unlike the CLI, end does not need start. observe_session takes no time range.

• Pagination: pass pageInfo.endCursor from a response back as nextCursor. For observe_metrics, observe_events, and observe_routes, also pass the returned startTime and endTime as start and end, and keep the other inputs the same. Routes paginate per platform. Session timelines paginate metrics and logs separately.

• Plan gating and usage: plan limits are the same as for the CLI. Each tool call counts toward the account's Expo MCP Server usage.

• Defaults and limits: observe_metrics sorts newest first by default. The CLI's --sort defaults to oldest. observe_routes takes a limit of up to 100, and the CLI takes up to 200. observe_events takes sort, and the CLI's observe:events has no --sort.

Supported Metrics

App-startup metrics

Navigation metrics

Emitted only when a navigation integration is enabled (SDK 56+). Measured per route name.

Which command takes which alias. observe:metrics (positional argument) and observe:metrics-summary --metric accept all nine aliases — startup and navigation. observe:routes --metric accepts only the three navigation aliases. Use the nav_ prefix everywhere; there are no bare cold_ttr / warm_ttr aliases.

observe:metrics also accepts a full metric name in place of an alias, for example eas observe:metrics expo.app_startup.tti. observe:routes accepts full navigation names the same way. The --metric flags on metrics-summary and routes are strict oclif options, so they take aliases only.

eas observe:metrics-summary

Shows per-version statistical aggregates for one or more metrics, with separate tables per platform.

# All default metrics, last 60 days, both platforms
eas observe:metrics-summary

# Single metric
eas observe:metrics-summary --metric tti

# Multiple metrics — each renders as its own table
eas observe:metrics-summary --metric tti --metric cold_launch

# Navigation metrics aggregate per version here, per route in observe:routes
eas observe:metrics-summary --metric nav_tti

# Choose which statistics to display
eas observe:metrics-summary --metric tti --stat median --stat p90 --stat eventCount

# Narrow time range and platform
eas observe:metrics-summary --metric tti --days 14 --platform ios

Stat flags: exactly min, median, max, average, p80, p90, p99, eventCount. This command takes no aliases — med, avg, and count are rejected here (they work only on observe:routes).

Default stats: median + eventCount in the table; all eight in JSON.

This command has no --limit, --after, --app-version, --build-number, or --update-id. It always aggregates every version in the time range.

Table layout:

• One table per metric (with merged value + event count cells, e.g. 0.45s (150))

• Each table shows iOS and Android in separate sections

• App Version column includes build numbers in parentheses (e.g. 1.2.0 (42))

• Footer row per platform shows total events per metric

• Update IDs are omitted from the table to keep output readable when a version has many updates; they are included in the JSON output as an array per version

JSON output shape:

{
  "versions": [
    {
      "appVersion": "1.2.0",
      "platform": "IOS",
      "buildNumbers": ["42"],
      "updateIds": ["abc-def-...", "..."],
      "metrics": {
        "expo.app_startup.tti": { "median": 0.45, "p90": 0.9, "...": "..." }
      }
    }
  ],
  "totalEventCounts": {
    "expo.app_startup.tti": { "IOS": 1234, "ANDROID": 890 }
  }
}

eas observe:metrics

Shows individual performance metric samples, paginated. The metric is a positional argument, not a flag. If omitted and running interactively, prompts for selection; in non-interactive mode it throws an error.

# Interactive: prompts for metric
eas observe:metrics

# Specify metric as positional arg
eas observe:metrics tti

# Navigation metrics work here too
eas observe:metrics nav_tti --sort slowest

# Filter by version or update, sort by slowest
eas observe:metrics tti --app-version 1.2.0 --sort slowest --limit 20

# Pagination — pass the endCursor from the previous run
eas observe:metrics tti --after <cursor>

Sample-specific flags:

• --sort <oldest|newest|slowest|fastest> — defaults to oldest

• --limit <N> — samples per page (default 10, max 100)

• --after <cursor> — pagination cursor from the previous run

• --app-version <version> — filter by app version string

• --build-number <number> — filter by app build number

• --update-id <id> — filter by EAS update ID

Table layout:

• Summary header shows the metric name, time range, and total sample count across all versions (e.g. TTI samples for the last 60 days — 1,234 total events)

• Columns: Value, App Version (with build number), Update (only when any sample has one), Platform, Device, Country, Timestamp

• When hasNextPage is true, prints Next page: --after <endCursor> hint below the table

• JSON output also includes sessionId, easClientId, and a customParams object per sample

eas observe:routes

Shows per-route statistical aggregates for navigation metrics (Cold TTR, Warm TTR, Nav TTI), grouped by route name with separate sections per platform.

# All three navigation metrics, default stats, last 60 days, both platforms
eas observe:routes

# Single metric, last 7 days, iOS only
eas observe:routes --metric nav_tti --days 7 --platform ios

# Multiple metrics and stats
eas observe:routes --metric nav_cold_ttr --metric nav_warm_ttr --stat median --stat p90 --stat count

# Filter to a single build
eas observe:routes --app-version 1.2.0 --build-number 42

# Narrow to specific routes (repeat the flag for multiple routes)
eas observe:routes --route-name /new --route-name /settings

# Pagination — each platform has its own cursor; pass the relevant endCursor
eas observe:routes --after <cursor>

Routes-specific flags:

• --metric <nav_cold_ttr|nav_warm_ttr|nav_tti> — navigation metric(s) to display, can be repeated. Defaults to all three.

• --stat <median|p90|count> — statistic(s) per metric. Aliases: med → median, event_count / eventCount → count.

• --limit <N> — routes per page (default 50, max 200, different from metrics/events which default to 10).

• --after <cursor> — pagination cursor from the previous run.

• --app-version <version> — filter by app version string.

• --build-number <number> — filter by app build number.

• --route-name <name> — filter by route name. Repeatable; only the listed routes are returned across both platforms. Duplicates are de-duplicated; omitting the flag returns all routes.

• --update-id <id> — filter by EAS update ID.

Default stats: median + count in the table; median, p90, count in JSON.

Table layout:

• Summary header with the chosen stats and time range, e.g. Med, P90 values (navigation count) for the last 7 days.

• Separate iOS and Android sections.

• First column is Route, followed by one column per metric/stat. With both display stats and count, cells are merged like 0.32s (1240).

• Each platform has its own pagination hint: Next page (iOS): --after <endCursor>.

JSON output shape:

{
  "routes": [
    {
      "routeName": "(tabs)/home",
      "platform": "IOS",
      "metrics": {
        "expo.navigation.cold_ttr": { "median": 0.32, "p90": 0.85, "count": 1240 },
        "expo.navigation.tti":       { "median": 0.55, "p90": 1.10, "count": 1240 }
      }
    }
  ],
  "pageInfoByPlatform": {
    "IOS":     { "hasNextPage": true,  "endCursor": "..." },
    "ANDROID": { "hasNextPage": false, "endCursor": null }
  }
}

eas observe:events

Shows custom events emitted by the app via the logEvent API in expo-observe. Behavior depends on what is passed:

# List the available custom event names and their counts (last 60 days)
eas observe:events

# All events across all names, last 7 days, iOS only
eas observe:events --all-events --days 7 --platform ios

# Only events with the given name
eas observe:events login_failed --limit 50

# Drill into a single session
eas observe:events --all-events --session-id <session-id>

# Pagination
eas observe:events login_failed --after <cursor>

Events-specific flags:

• --all-events — when no event name argument is given, list all events instead of the name summary. Cannot be combined with an event name argument.

• --session-id <id> — filter to events from a single session (events-only). With no event name argument, this lists the session's events instead of the event-name summary. For the full timeline — metrics as well as log events — use observe:session.

• --app-version <version> — filter by app version string

• --build-number <number> — filter by app build number

• --update-id <id> — filter by EAS update ID

• --limit <N> — events per page (default 10, max 100)

• --after <cursor> — pagination cursor

Table layout (event listings):

• Summary header: <event-name> events <time range> or Custom events <time range> for --all-events, with a total event count when available

• Columns: Timestamp, Event (only when listing across multiple names), Severity (only when at least one event in the page has a severity), App Version (with build number), Platform, Device, Country

• Next page: --after <endCursor> hint below the table when there is a next page

Empty-result helper: if a specific event name is queried and returns no events, the command prints a yellow No events found matching "<name>" warning followed by the available event names + counts in the same time range — useful for fixing typos.

Truncation note: the event-names summary may flag Result is truncated; not all event names are shown. when there are more names than the server returns in a single response.

JSON output shape (event listing):

{
  "events": [
    {
      "id": "...",
      "eventName": "login_failed",
      "timestamp": "2026-...",
      "sessionId": "...",
      "severityNumber": 13,
      "severityText": "WARN",
      "properties": [{ "key": "reason", "value": "bad_password", "type": "string" }],
      "appVersion": "1.2.0",
      "appBuildNumber": "42",
      "appUpdateId": null,
      "appEasBuildId": null,
      "deviceModel": "...",
      "deviceOs": "iOS",
      "deviceOsVersion": "17.4",
      "countryCode": "US",
      "environment": "production",
      "easClientId": "..."
    }
  ],
  "pageInfo": { "hasNextPage": true, "endCursor": "..." }
}

The name-summary mode returns { "names": [{ "eventName": "...", "count": 123 }], "isTruncated": false }.

eas observe:session

Shows the full timeline of metric and log events for a single session — the CLI equivalent of the dashboard's session view. Use it after observe:metrics surfaces a slow sample: take that sample's sessionId (present in --json output) and replay everything that session recorded.

# Interactive: pick a metric, then pick a session from the candidate list
eas observe:session

# Inspect a known session
eas observe:session <session-id>

# Pick a session from the slowest TTI events in the last 7 days
eas observe:session --event-name tti --sort slowest --days 7

Session-specific flags:

• [SESSIONID] — positional. Omit it in interactive mode to choose from a list. Required in non-interactive mode, including under --json.

• --event-name <name> — metric or log event used to build the candidate session list (for example tti, cold_launch, login_pressed). Prompts when omitted in interactive mode.

• --sort <slowest|fastest|newest|oldest> — orders the candidate events. Prompts when omitted in interactive mode. No default, unlike observe:metrics.

The picker flags and the session ID are mutually exclusive. --event-name, --sort, --days, --start, and --end describe how to find a session, so passing any of them together with a session ID throws. Query a known session with the ID alone.

This command has no --platform, --limit, or --after flag. It takes the shared time-range, --environment, --project-id, --json, and --non-interactive flags.

JSON output shape:

{
  "sessionId": "...",
  "metadata": { "...": "..." },
  "entries": [{ "...": "..." }],
  "hasMoreMetricEvents": false,
  "hasMoreLogEvents": false
}

entries interleaves metric and log events for the session. The two hasMore* flags report truncation per event kind; there is no cursor to page with.

eas observe:errors

Shows error and exception groups, grouped by fingerprint, with event, user, and session counts for each group. The fingerprint is in the first column. Pass --fingerprint to list the occurrences of one group, with stack traces, instead of the grouped summary. Error reporting setup is in ./setup.md.

# Error groups, last 7 days
eas observe:errors --days 7

# Only fatal errors on Android
eas observe:errors --severity fatal --platform android

# Occurrences of one group, with stack traces
eas observe:errors --fingerprint <fingerprint>

Errors-specific flags:

• --fingerprint <value> — show the occurrences of this error group instead of the grouped summary

• --severity <fatal|error> — filter by severity (ignored when --fingerprint is set)

• --app-version <version>, --build-number <number>, --update-id <id> — filter by version, build, or EAS update

• --limit <N> — occurrences per page (default 10, max 100). Requires --fingerprint.

• --after <cursor> — pagination cursor. Requires --fingerprint.

--limit or --after without --fingerprint fails with an error. The grouped summary has no pagination.

eas observe:event

Shows one metric, log, or error event by its ID. Event IDs are in the --json output of observe:metrics, observe:events, and observe:session, and in the occurrences from observe:errors --fingerprint.

eas observe:event <event-id>
eas observe:event <event-id> --json

ID is a required positional argument. The command takes only --project-id, --json, and --non-interactive.

eas observe:versions

Shows app version hierarchy with build numbers, OTA update IDs, and event counts per version.

# Both platforms, last 60 days
eas observe:versions

# iOS only, last 14 days
eas observe:versions --days 14 --platform ios

No metric-related flags. Output shows separate iOS and Android tables with columns: App Version, First Seen, Events, Users, Builds (count), Updates (count).

JSON output returns the full nested hierarchy with buildNumbers[].easBuilds[] and updates[].easBuilds[], including firstSeenAt, eventCount, and uniqueUserCount at every level.

Common Workflows

"What are my app's startup times right now?"

eas observe:metrics-summary --days 7 --stat median --stat p90

"Which TTI samples were slowest this week?"

eas observe:metrics tti --sort slowest --days 7 --limit 20

"How fast are over-the-air updates downloading in the field?"

eas observe:metrics-summary --metric update_download --days 7

"Which screens are slowest to navigate to?"

eas observe:routes --metric nav_tti --stat median --stat p90 --days 7

"What happened during that one slow session?"

eas observe:metrics tti --sort slowest --days 7 --json   # read sessionId from a sample
eas observe:session <session-id>

"How does navigation perform on just the routes I care about?"

eas observe:routes --route-name /home --route-name /checkout --days 7

"What custom events is my app emitting?"

eas observe:events --days 7

"Show me every error event from one user's session."

eas observe:events --all-events --session-id <session-id>

"What versions of my app are in the field?"

eas observe:versions

"Show me metrics for a specific project without needing to be in the repo"

eas observe:metrics-summary --project-id <uuid> --metric tti

"Get JSON for scripting"

eas observe:metrics-summary --metric tti --json --non-interactive

Notes

• Requires the user to be logged in (eas login).

• When --project-id is provided, the command does not require running inside an EAS project directory; otherwise the project ID is read from the local app.config / app.json. If using this option, ensure that you are logged in as a user that has access to the specified project.

• observe:metrics-summary does not print update IDs in the table but still returns them in JSON for scripting or piping into other commands.