Skip to content
FlagSwiftDocs

Audit, events and metrics

Who changed what, what happened, and how your flags are being used.

Concepts#

Three views of what happened#

Which one to use
ViewDescription
Audit logThe exact, append-only record: actor, request id, IP address, and the before and after values. Use it to answer “who changed this, and what was it before”.
EventsThe same records, grouped into readable types and categories with a severity and a one-line summary. Several audit actions can be one event type (every kind of change to a flag is flag.changed). Before and after values stay in the audit log.
MetricsCounts of evaluations and API calls per hour, kept for 30 days. They say how flags are used, not who changed them.

Events and the audit log share storage, retention and access rules, so the same people see the same records. A developer sees only the entries for their own actions.

How metrics are measured#

  • Evaluation counts are buffered in memory and written every 10 seconds, so a number can lag a little behind live traffic.
  • A window covers the last days days up to and including the current hour. It is hourly for 1 or 2 days and daily beyond that. collectingSince is the oldest data kept; earlier time reads as zero.
  • Results are cached briefly, so repeating a call within moments may return the same numbers.
  • METRICS_ENABLED=false stops counting; reads keep working on what exists.
  • Each evaluation records a reason such as RULE_MATCH, ROLLOUT_IN, DISABLED or KILL_SWITCH, so you can see why flags served what they did.

Prometheus versus the console metrics#

The Prometheus endpoint is for operators: counters and gauges for this one server instance that reset when it restarts, scraped by your own monitoring. The metrics endpoints above are stored per project and survive restarts, and feed the console. Use Prometheus for dashboards and paging on the service, and the metrics endpoints for how flags are used.

Audit log#

The audit log records every change with the actor, the request id and the before and after values. It is append-only; nothing here edits it.

List entries#

GET/api/audit-logs

Newest first. actorType is user, api_key or system. search matches the actor's email and the resource name. Developers see only their own actions.

Authorization

audit.read

Query parameters

  • resourceTypestring

    One of flag, project, environment, member, api_key, segment, audit_log, release, alert_rule, organization, role.
  • actionstring

    One action, such as flag.toggled, flag.moved, kill_switch.enabled, release.approved, member.role_changed, api_key.revealed or config.imported. Only known actions are accepted; anything else is a 400.
  • searchstring

    Up to 100 characters. Matches actor email and resource name.
  • fromISO date-time

    Only entries at or after this time. Leave it out for no lower bound.
  • toISO date-time

    Only entries before this time (not included). Leave it out for no upper bound.
  • pageinteger

    Page number, from 1. Default 1.
  • limitinteger

    Entries per page, 1 to 100. Default 25.

Errors

  • 400A resourceType or action that is not in the lists, a search over 100 characters, a from or to that is not a date, or a bad page or limit.
  • 401No session, or it has expired (“Authentication required”).
  • 403Your role lacks audit.read, or the organization is deactivated.
Request
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/audit-logs?resourceType=flag&action=flag.toggled&from=2026-10-01T00:00:00Z&limit=25"
200OK
{
  "status": "success",
  "message": "OK",
  "data": {
    "items": [
      {
        "id": "e1c9a7b4-2d36-4f08-b1a2-6a0f3c8d5e91",
        "action": "flag.toggled",
        "resourceType": "flag",
        "resourceId": "FLAG_ID",
        "resourceName": "checkout-v2",
        "projectId": "PROJECT_ID",
        "environment": "production",
        "actorType": "user",
        "actorEmail": "rm@example.com",
        "previousValue": { "enabled": false },
        "newValue": { "enabled": true },
        "ipAddress": "203.0.113.24",
        "userAgent": "Mozilla/5.0 ...",
        "requestId": "7d2f0c1e-93aa-4b57-8c40-5be1f2a9d610",
        "createdAt": "2026-10-03T09:12:31.000Z"
      }
    ],
    "pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1, "hasNext": false, "hasPrev": false }
  }
}

Export#

GET/api/audit-logs/export

Same filters as List entries, no paging. format is csv (the default) or json. Auditors and admins hold this permission; developers do not.

  • The body is a file, not the JSON envelope. The name is audit-log-YYYY-MM-DD.csv or .json.
  • At most 10,000 rows, newest first. X-Export-Rows says how many came back and X-Export-Truncated: true says the cap cut it short: narrow the dates and export again.
  • In CSV, values that start with a spreadsheet formula character are prefixed with an apostrophe so opening the file cannot run them. Lines end with CRLF.
  • The export is itself recorded in the audit log as audit.exported.

Authorization

audit.export

Query parameters

  • formatcsv | json

    File format. Default csv.
  • resourceTypestring

    Same values as List entries.
  • actionstring

    Same values as List entries.
  • searchstring

    Up to 100 characters. Matches actor email and resource name.
  • fromISO date-time

    Only entries at or after this time.
  • toISO date-time

    Only entries before this time (not included).

Errors

  • 400A format other than csv or json, or a bad filter.
  • 401No session, or it has expired (“Authentication required”).
  • 403Your role lacks audit.export (auditors and admins hold it).
Request
curl -s -b "auth_session=$SESSION" -D - -o audit.csv \
  "$FLAGSWIFT_URL/api/audit-logs/export?format=csv&resourceType=api_key&from=2026-09-01T00:00:00Z"
200OK
HTTP/1.1 200 OK
Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="audit-log-2026-10-03.csv"
Cache-Control: no-store
X-Export-Rows: 2
X-Export-Truncated: false

createdAt,action,resourceType,resourceId,resourceName,projectId,environment,actorType,actorEmail,ipAddress,requestId,previousValue,newValue
2026-09-28T13:02:11.000Z,api_key.created,api_key,KEY_ID,Checkout server,PROJECT_ID,production,user,rm@example.com,203.0.113.24,7d2f0c1e-...,,"{""type"":""server""}"
2026-09-30T08:40:02.000Z,api_key.revoked,api_key,KEY_ID,Checkout server,PROJECT_ID,production,user,admin@example.com,203.0.113.9,a41e90bb-...,,

Event feed#

List events#

GET/api/events

Events are the readable story (a release failed, an alert rule changed); the audit log is the exact record. severity is info or warning: warnings mark things like deletes, the kill switch, a failed release, a revoked key or a password reset. Developers see only their own events.

Authorization

audit.read

Query parameters

  • categorystring

    flags, releases, security or configuration.
  • typestring

    One event type, such as flag.changed, release.completed, kill_switch.activated, api_key.revoked or member.removed. An unknown type is a 400. When you send both, only events matching both are returned.
  • searchstring

    Up to 100 characters.
  • fromISO date-time

    Only events at or after this time.
  • toISO date-time

    Only events before this time (not included).
  • pageinteger

    Page number, from 1. Default 1.
  • limitinteger

    Events per page, 1 to 100. Default 25.

Errors

  • 400A category or type that does not exist, a search over 100 characters, a bad date, or a bad page or limit.
  • 401No session, or it has expired (“Authentication required”).
  • 403Your role lacks audit.read, or the organization is deactivated.
Request
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/events?category=releases&limit=10"
200OK
{
  "status": "success",
  "message": "OK",
  "data": {
    "items": [
      {
        "id": "5a0e7b12-8c3d-4f61-9d24-b7e0a1c63f85",
        "type": "release.failed",
        "category": "releases",
        "severity": "warning",
        "summary": "Release step failed",
        "subject": { "type": "release", "id": "RELEASE_ID", "name": "Checkout v2: Ramp to everyone" },
        "projectId": "PROJECT_ID",
        "environment": "production",
        "actor": { "type": "user", "email": "rm@example.com" },
        "requestId": "release:RELEASE_ID",
        "at": "2026-10-05T11:00:02.000Z"
      }
    ],
    "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1, "hasNext": false, "hasPrev": false }
  }
}

Actions and event types#

Every audit entry has an action, and the event feed maps each action to an event type in one of four categories, with a severity of info or warning (destructive or security-sensitive actions are warnings). Filter the audit log by action and the event feed by type or category. These are all of them.

Flags category
Audit actionEvent typeDescription
flag.createdflag.createdInfo severity.
flag.updatedflag.changedInfo severity.
flag.movedflag.changedInfo severity.
flag.variants_updatedflag.changedInfo severity.
flag.toggledflag.changedInfo severity.
rollout.updatedflag.changedInfo severity.
targeting.updatedflag.changedInfo severity.
flag.archivedflag.archivedInfo severity.
flag.restoredflag.restoredInfo severity.
flag.deletedflag.deletedWarning severity.
kill_switch.enabledkill_switch.activatedWarning severity.
kill_switch.restoredkill_switch.liftedInfo severity.
Releases category
Audit actionEvent typeDescription
rollout.rollbackrelease.rolled_backWarning severity.
release.createdrelease.proposedInfo severity.
release.approvedrelease.approvedInfo severity.
release.rejectedrelease.rejectedInfo severity.
release.cancelledrelease.cancelledInfo severity.
release.step_appliedrelease.step_appliedInfo severity.
release.step_failedrelease.failedWarning severity.
release.completedrelease.completedInfo severity.
Security category
Audit actionEvent typeDescription
api_key.createdapi_key.createdInfo severity.
api_key.rotatedapi_key.rotatedInfo severity.
api_key.revokedapi_key.revokedWarning severity.
api_key.revealedapi_key.revealedInfo severity.
member.role_changedmember.role_changedInfo severity.
member.ownership_transferredmember.ownership_transferredWarning severity.
member.removedmember.removedWarning severity.
member.invitedmember.invitedInfo severity.
member.invite_revokedmember.invite_revokedInfo severity.
member.joinedmember.joinedInfo severity.
member.password_changedmember.password_changedInfo severity.
member.password_resetmember.password_resetWarning severity.
member.sessions_revokedmember.sessions_revokedInfo severity.
audit.exportedaudit.exportedInfo severity.
config.exportedconfig.exportedInfo severity.
config.importedconfig.importedInfo severity.
role.createdrole.createdInfo severity.
role.updatedrole.updatedInfo severity.
role.deletedrole.deletedWarning severity.
Configuration category
Audit actionEvent typeDescription
project.createdproject.createdInfo severity.
project.updatedproject.updatedInfo severity.
project.archivedproject.archivedInfo severity.
project.restoredproject.restoredInfo severity.
project.deletedproject.deletedWarning severity.
environment.createdenvironment.createdInfo severity.
environment.updatedenvironment.updatedInfo severity.
environment.deletedenvironment.deletedWarning severity.
environment.reorderedenvironment.reorderedInfo severity.
segment.createdsegment.createdInfo severity.
segment.updatedsegment.updatedInfo severity.
segment.deletedsegment.deletedInfo severity.
alert.createdalert.createdInfo severity.
alert.updatedalert.updatedInfo severity.
alert.deletedalert.deletedInfo severity.
organization.updatedorganization.updatedInfo severity.
organization.deactivatedorganization.deactivatedInfo severity.
organization.reactivatedorganization.reactivatedInfo severity.

Metrics#

The project, report, summary, stale and errors endpoints need metrics.read; the per-flag one needs flags.read. Each takes a time range in days (1 to 30).

Usage for a project#

GET/api/metrics?projectId=…

enabled counts evaluations that served the flag as on. flags lists the busiest at most 50 flags first. variants is empty for flags without variants.

Authorization

metrics.read

Query parameters

  • projectIdstringRequired

    The project. A project that is not in your organization is a 404.
  • environmentstring

    Limit to one environment, by name (up to 50 characters). Leave it out for all environments.
  • daysinteger

    How many days back, a whole number from 1 to 30. Default 7. A value outside that is a 400 (“days can be at most 30”).

Errors

  • 400“Project is required” (where a project is needed), or a days that is not a whole number from 1 to 30 (“days must be a number”, “days must be a whole number”, “days must be at least 1”, “days can be at most 30”).
  • 401No session, or it has expired (“Authentication required”).
  • 403Your role lacks metrics.read, or the organization is deactivated.
  • 404The project does not exist in your organization.
Request
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/metrics?projectId=PROJECT_ID&environment=production&days=7"
200OK
{
  "status": "success",
  "message": "OK",
  "data": {
    "days": 7,
    "granularity": "day",
    "from": "2026-09-26T11:00:00.000Z",
    "to": "2026-10-03T11:00:00.000Z",
    "collectingSince": "2026-09-20T00:00:00.000Z",
    "projectId": "PROJECT_ID",
    "environment": "production",
    "totals": { "evaluations": 184230, "enabled": 121004 },
    "series": [
      { "t": "2026-09-26T00:00:00.000Z", "evaluations": 24810, "enabled": 16102 }
    ],
    "flags": [
      {
        "flagKey": "checkout-v2",
        "displayName": "Checkout v2",
        "evaluations": 90412,
        "enabled": 61230,
        "lastEvaluatedAt": "2026-10-03T10:00:00.000Z",
        "variants": { "control": 29182, "new": 61230 }
      }
    ],
    "reasons": [ { "reason": "ROLLOUT_IN", "count": 61230 }, { "reason": "DISABLED", "count": 29182 } ],
    "environments": [ { "environment": "production", "evaluations": 184230 } ]
  }
}

Report#

GET/api/metrics/report?projectId=…

The same parameters as the project call, for the report view on the Metrics page. It lists every active (not archived) flag in the project, including flags nobody evaluated, which show evaluations: 0. Archived flags are left out. At most 1000 flags, busiest first.

Authorization

metrics.read

Query parameters

  • projectIdstringRequired

    The project. A project that is not in your organization is a 404.
  • environmentstring

    Limit to one environment, by name (up to 50 characters). Leave it out for all environments.
  • daysinteger

    How many days back, a whole number from 1 to 30. Default 7. A value outside that is a 400 (“days can be at most 30”).

Errors

  • 400“Project is required” (where a project is needed), or a days that is not a whole number from 1 to 30 (“days must be a number”, “days must be a whole number”, “days must be at least 1”, “days can be at most 30”).
  • 401No session, or it has expired (“Authentication required”).
  • 403Your role lacks metrics.read, or the organization is deactivated.
  • 404The project does not exist in your organization.
Request
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/metrics/report?projectId=PROJECT_ID&days=30"
200OK
{
  "status": "success",
  "message": "OK",
  "data": {
    "days": 30,
    "granularity": "day",
    "from": "2026-09-03T11:00:00.000Z",
    "to": "2026-10-03T11:00:00.000Z",
    "collectingSince": "2026-09-20T00:00:00.000Z",
    "projectId": "PROJECT_ID",
    "environment": null,
    "totals": { "evaluations": 640112, "enabled": 402918 },
    "items": [
      {
        "id": "FLAG_ID",
        "name": "checkout-v2",
        "displayName": "Checkout v2",
        "type": "boolean",
        "createdAt": "2026-08-14T09:30:00.000Z",
        "evaluations": 310442,
        "enabled": 201998,
        "lastEvaluatedAt": "2026-10-03T10:00:00.000Z",
        "environmentsOn": ["production", "staging"]
      }
    ]
  }
}

Organization summary#

GET/api/metrics/summary

No project is needed. The stale block always uses a 14-day threshold and lists the five oldest flags.

Authorization

metrics.read

Query parameters

  • daysinteger

    How many days back, a whole number from 1 to 30. Default 7. A value outside that is a 400 (“days can be at most 30”).

Errors

  • 400“Project is required” (where a project is needed), or a days that is not a whole number from 1 to 30 (“days must be a number”, “days must be a whole number”, “days must be at least 1”, “days can be at most 30”).
  • 401No session, or it has expired (“Authentication required”).
  • 403Your role lacks metrics.read, or the organization is deactivated.
Request
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/metrics/summary?days=7"
200OK
{
  "status": "success",
  "message": "OK",
  "data": {
    "days": 7,
    "granularity": "day",
    "from": "2026-09-26T11:00:00.000Z",
    "to": "2026-10-03T11:00:00.000Z",
    "collectingSince": "2026-09-20T00:00:00.000Z",
    "totals": { "evaluations": 402118, "enabled": 250440 },
    "series": [ { "t": "2026-09-26T00:00:00.000Z", "evaluations": 55120, "enabled": 34010 } ],
    "projects": [ { "projectId": "PROJECT_ID", "name": "Web app", "evaluations": 402118 } ],
    "stale": {
      "thresholdDays": 14,
      "count": 3,
      "byReason": { "unused": 1, "fully_rolled_out": 1, "off_everywhere": 1 },
      "items": [
        {
          "id": "FLAG_ID",
          "name": "old-banner",
          "displayName": "Old banner",
          "projectId": "PROJECT_ID",
          "createdAt": "2026-06-01T08:00:00.000Z",
          "lastChangedAt": "2026-07-12T14:20:00.000Z",
          "reasons": ["unused"],
          "enabledIn": []
        }
      ]
    }
  }
}

Stale flags#

GET/api/metrics/stale?projectId=…

Active flags older than the threshold that look finished or forgotten, which are candidates for cleanup. Each flag carries one or more reasons: unused (nobody evaluated it in the period), fully_rolled_out or off_everywhere. warmingUp is true when counting began less than the threshold ago, so an unused flag may simply not have been counted for long enough yet.

Authorization

metrics.read

Query parameters

  • projectIdstringRequired

    The project. A project that is not in your organization is a 404.
  • daysinteger

    How many days without a single evaluation make a flag stale, a whole number from 1 to 30. Default 14.

Errors

  • 400“Project is required” (where a project is needed), or a days that is not a whole number from 1 to 30 (“days must be a number”, “days must be a whole number”, “days must be at least 1”, “days can be at most 30”).
  • 401No session, or it has expired (“Authentication required”).
  • 403Your role lacks metrics.read, or the organization is deactivated.
  • 404The project does not exist in your organization.
Request
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/metrics/stale?projectId=PROJECT_ID&days=14"
200OK
{
  "status": "success",
  "message": "OK",
  "data": {
    "projectId": "PROJECT_ID",
    "thresholdDays": 14,
    "collectingSince": "2026-09-20T00:00:00.000Z",
    "warmingUp": false,
    "items": [
      {
        "id": "FLAG_ID",
        "name": "old-banner",
        "displayName": "Old banner",
        "projectId": "PROJECT_ID",
        "createdAt": "2026-06-01T08:00:00.000Z",
        "lastChangedAt": "2026-07-12T14:20:00.000Z",
        "reasons": ["unused", "off_everywhere"],
        "enabledIn": []
      }
    ]
  }
}

One flag#

GET/api/flags/{id}/metrics

Every environment the flag is configured in is listed, even with no traffic.

Authorization

flags.read

Path parameters

  • idstringRequired

    The flag id.

Query parameters

  • environmentstring

    Limit to one environment, by name (up to 50 characters). Leave it out for all environments.
  • daysinteger

    How many days back, a whole number from 1 to 30. Default 7. A value outside that is a 400 (“days can be at most 30”).

Errors

  • 400“Project is required” (where a project is needed), or a days that is not a whole number from 1 to 30 (“days must be a number”, “days must be a whole number”, “days must be at least 1”, “days can be at most 30”).
  • 401No session, or it has expired (“Authentication required”).
  • 403Your role lacks flags.read.
  • 404“Flag not found”.
Request
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/flags/FLAG_ID/metrics?environment=production&days=7"
200OK
{
  "status": "success",
  "message": "OK",
  "data": {
    "days": 7,
    "granularity": "day",
    "from": "2026-09-26T11:00:00.000Z",
    "to": "2026-10-03T11:00:00.000Z",
    "collectingSince": "2026-09-20T00:00:00.000Z",
    "flagId": "FLAG_ID",
    "flagKey": "checkout-v2",
    "environments": [
      {
        "environment": "production",
        "evaluations": 90412,
        "enabled": 61230,
        "lastEvaluatedAt": "2026-10-03T10:00:00.000Z",
        "variants": { "control": 29182, "new": 61230 },
        "reasons": { "ROLLOUT_IN": 61230, "DISABLED": 29182 }
      }
    ],
    "series": [ { "t": "2026-09-26T00:00:00.000Z", "evaluations": 12010, "enabled": 8100 } ]
  }
}

Errors#

GET/api/observability/errors?projectId=…

Evaluation errors, from the server and as reported by SDKs. SDKs report them with POST /api/v1/evaluation/errors; see the Evaluation API. errorRate is a percentage of API requests, or null with no requests. SDK-reported errors are counted in sdkReported and the breakdowns, not in the rate. Latency percentiles are estimated: each is the upper bound of the latency bucket that holds it (5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000 ms). The byFlag and bySdk lists are cut at 20.

Authorization

metrics.read

Query parameters

  • projectIdstringRequired

    The project. A project that is not in your organization is a 404.
  • environmentstring

    Limit to one environment, by name (up to 50 characters). Leave it out for all environments.
  • daysinteger

    How many days back, a whole number from 1 to 30. Default 7. A value outside that is a 400 (“days can be at most 30”).

Errors

  • 400“Project is required” (where a project is needed), or a days that is not a whole number from 1 to 30 (“days must be a number”, “days must be a whole number”, “days must be at least 1”, “days can be at most 30”).
  • 401No session, or it has expired (“Authentication required”).
  • 403Your role lacks metrics.read, or the organization is deactivated.
  • 404The project does not exist in your organization.
Request
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/observability/errors?projectId=PROJECT_ID&days=1"
200OK
{
  "status": "success",
  "message": "OK",
  "data": {
    "days": 1,
    "granularity": "hour",
    "from": "2026-10-02T11:00:00.000Z",
    "to": "2026-10-03T11:00:00.000Z",
    "collectingSince": "2026-09-20T00:00:00.000Z",
    "projectId": "PROJECT_ID",
    "environment": null,
    "totals": { "requests": 48210, "errors": 96, "errorRate": 0.2, "sdkReported": 14 },
    "latency": { "samples": 48210, "avgMs": 18.4, "p50Ms": 10, "p95Ms": 50 },
    "series": [ { "t": "2026-10-02T11:00:00.000Z", "requests": 2010, "errors": 4 } ],
    "byType": [ { "errorType": "network", "count": 14 } ],
    "byFlag": [ { "flagKey": "checkout-v2", "count": 9 } ],
    "bySdk": [ { "sdk": "node/1.2.0", "count": 20 } ],
    "byEndpoint": [ { "endpoint": "evaluation.server", "requests": 30110, "errors": 60, "p95Ms": 25 } ],
    "byEnvironment": [ { "environment": "production", "errors": 96 } ]
  }
}

Prometheus#

Scrape#

GET/api/prometheus

Plain-text metrics in the Prometheus format. Off (a 404) unless METRICS_TOKEN is set, and then it needs that token as a bearer token, because metrics describe traffic. It does not use a session or an API key, and its errors are not the usual envelope.

Series exposed
MetricTypeDescription
flagswift_evaluations_totalcounterEvaluations served, by outcome (on or off).
flagswift_evaluation_errors_totalcounterFailed evaluation API calls and SDK-reported errors, by error_type.
flagswift_api_requests_totalcounterEvaluation API requests, by endpoint and status.
flagswift_api_request_duration_mshistogramEvaluation API duration in milliseconds, by endpoint.
flagswift_flag_changes_totalcounterFlag changes, by audit action.
flagswift_release_changes_totalcounterRelease events, by audit action.
flagswift_cache_hits_total, flagswift_cache_misses_totalcounterCache lookups, by cache (config or key).
flagswift_realtime_connectionsgaugeOpen real-time streams on this instance.
flagswift_buffered_countersgaugeCounts waiting to be written, by recorder (evaluations or api).
flagswift_uptime_secondsgaugeSeconds since this instance started.

Authorization

bearer METRICS_TOKEN

Errors

  • 404The endpoint is off because METRICS_TOKEN is not set. The body is { "error": "Not Found" }.
  • 401The bearer token is missing or wrong. The reply has WWW-Authenticate: Bearer and the body { "error": "Unauthorized" }.
Request
curl -s -H "Authorization: Bearer $METRICS_TOKEN" "$FLAGSWIFT_URL/api/prometheus"
200OK
# HELP flagswift_evaluations_total Flag evaluations served, by outcome.
# TYPE flagswift_evaluations_total counter
flagswift_evaluations_total{outcome="on"} 1204
flagswift_evaluations_total{outcome="off"} 311
# HELP flagswift_api_requests_total Evaluation API requests, by endpoint and status.
# TYPE flagswift_api_requests_total counter
flagswift_api_requests_total{endpoint="evaluation.server",status="200"} 902
# HELP flagswift_api_request_duration_ms Evaluation API request duration in milliseconds.
# TYPE flagswift_api_request_duration_ms histogram
# HELP flagswift_realtime_connections Open real-time change streams (SSE) on this instance.
# TYPE flagswift_realtime_connections gauge
flagswift_realtime_connections 7
# HELP flagswift_uptime_seconds Seconds since this instance started.
# TYPE flagswift_uptime_seconds gauge
flagswift_uptime_seconds 86412
prometheus.yml
scrape_configs:
  - job_name: flagswift
    metrics_path: /api/prometheus
    authorization:
      credentials: YOUR_METRICS_TOKEN
    static_configs:
      - targets: ["flags.example.com"]

Why not /metrics

That path is the console's Metrics page, so the scrape endpoint lives under /api.
  • The Observability guide lists the gauges and what each one means.
  • With several instances, scrape each one: values are per instance and counters restart from zero when it restarts.

Common patterns#

Who turned this flag on, and what was it before?#

bash
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/audit-logs?resourceType=flag&action=flag.toggled&search=checkout-v2&limit=5" \
  | jq '.data.items[] | {at: .createdAt, who: .actorEmail, env: .environment, from: .previousValue, to: .newValue}'

Export last month's audit trail for a review#

bash
curl -s -b "auth_session=$SESSION" -D headers.txt -o audit-sep.json \
  "$FLAGSWIFT_URL/api/audit-logs/export?format=json&from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z"

# If this says true, the 10,000 row cap cut it short: split the range and export again
grep -i x-export-truncated headers.txt

Find flags to clean up#

bash
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/metrics/stale?projectId=PROJECT_ID&days=30" \
  | jq '{warmingUp: .data.warmingUp, flags: [.data.items[] | {name, reasons}]}'