togglddocs
Dashboard
GuidesAPI reference
Analytics

Retrieve flag analytics

GET
/api/v1/flags/{key}/analytics

Returns evaluation counts for one flag in the credential's environment, over the last hour, 24 hours, or 7 days. The counts come from telemetry, so new evaluations can take a short time to appear.

Requires a management key. Evaluation keys and public tokens get 403.

Returns 404 if no flag has this key.

Authorization

bearer
headerAuthorizationBearer <token>

Send a credential in the Authorization header: Authorization: Bearer <token>. Each credential belongs to one environment of one workspace, so the API never takes a workspace or environment in the URL.

  • Management key (ffk_…, secret): manages flags, segments, environments, and API keys, and reads the audit log and analytics. It can also do everything an evaluation key can.
  • Evaluation key (ffk_…, secret): for server SDKs. It evaluates flags, reads flag definitions for local evaluation, and sends telemetry.
  • Public token (ffp_…, not secret): for browser and mobile apps. It evaluates flags through OFREP and sends telemetry. It cannot read flag definitions.

Keep secret keys on your server. A 401 response means the credential is missing or not valid. A 403 response means the credential is valid but its role cannot perform the operation.

Path Parameters

key*string

The flag key, such as new-checkout.

Query Parameters

range?string

The time range. 1h returns 1-minute buckets. 24h and 7d return 1-hour buckets. Defaults to 24h.

Value in"1h""24h""7d"

Response Body

OK

application/json
  1. response

Evaluation counts for one flag in the credential's environment.

range*string

The time range of the report.

Value in"1h""24h""7d"
from*string

The start of the report, as an ISO 8601 timestamp.

to*string

The end of the report (the current time), as an ISO 8601 timestamp.

total*number|
errors*number|
lastEvaluatedAt*|

The start of the latest minute with an evaluation in the range. null if there were none.

timeline*array<>

Evaluation counts over time, oldest first. Buckets are 1 minute for 1h and 1 hour for 24h and 7d. Empty buckets have a count of 0.

variants*array<>

Evaluation counts for each served variant, largest first.

Example Request
curl -X GET 'https://api.toggld.io/api/v1/flags/string/analytics'
Example Response
{  "range": "1h",  "from": "2026-05-02T08:31:00.000Z",  "to": "2026-05-02T09:30:42.000Z",  "total": 913,  "errors": 0,  "lastEvaluatedAt": "2026-05-02T09:30:00.000Z",  "timeline": [    {      "bucketStart": "2026-05-02T09:29:00.000Z",      "count": 0    },    {      "bucketStart": "2026-05-02T09:30:00.000Z",      "count": 913    }  ],  "variants": [    {      "variant": "off",      "count": 731    },    {      "variant": "on",      "count": 182    }  ]}

List audit events GET

Returns up to 100 of the most recent configuration changes in the workspace, newest first. Use the query parameters to filter the events. When you combine filters, an event must match all of them. Requires a management key.

Evaluate a flag POST

Evaluates one flag for the evaluation context in the request body. Returns the value, the variant, and the reason it was served. Accepts an evaluation key, a management key, or a public token. Returns `404` with `FLAG_NOT_FOUND` if the flag does not exist in the credential's environment. Returns `400` if evaluation fails, such as `TARGETING_KEY_MISSING` when a percentage rollout needs a `targetingKey`. A request body that is not valid JSON returns `400` with `PARSE_ERROR`, and a JSON body that is not a valid evaluation request returns `400` with `INVALID_CONTEXT`.