Skip to content
Featureflip Docs

Records analytics events from a client SDK.

POST
/v1/client/events
 
curl --request POST \
  --url https://eval.featureflip.io/v1/client/events \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "events": [ { "type": "Evaluation", "flagKey": "example", "userId": "example", "variation": "example", "timestamp": "2026-04-15T12:00:00Z", "metadata": { "additionalProperty": "example" }, "prerequisiteKey": "example", "reason": "example", "ruleId": "example" } ] }'

The client-surface counterpart of POST /v1/sdk/events, for SDKs that authenticate with a client key. The mobile SDKs (Swift, Android, Flutter) use this to report track() calls. Server SDKs keep using /v1/sdk/events.

A client that sends X-Featureflip-Reports-Evaluations: 1 on evaluate and identify reports the flags its code actually reads here, as Evaluation events (one per flag, variation and user is enough). For clients that don’t send the header, this API records the evaluations it serves on their behalf.

Because a client key is public by design, this endpoint is rate limited per client IP, limits the size of a request, and caps the number of events in one request. An event that exceeds one of the following per-event limits is discarded on its own; the rest of the batch is still recorded, and the response is unchanged:

  • its timestamp sits far outside the present;
  • its flagKey is longer than 256 characters;
  • it is a Custom event introducing more than 50 distinct event keys in one request. Repeats of a key already in the request are always recorded, so this bounds how many distinct event names a single batch can introduce, not how many events it may carry.

Authorizations

Section titled “ Authorizations ”

Request Body

Section titled “ Request Body ”

Batch of events to record.

object
events
required
Array<object>
nullable
object
type
required
string
Allowed values: Evaluation Impression Identify Custom
flagKey
required
string
nullable
userId
string
nullable
variation
string
nullable
timestamp
string format: date-time
metadata
object
key
additional properties
prerequisiteKey
string
nullable
reason

Optional. Why the evaluation served its variation: rule-match, fallthrough, flag-disabled, prerequisite-failed, error or flag-not-found. Used to attribute evaluation traffic in flag analytics; events without it count as an unknown source.

string
nullable
ruleId

Optional. The id of the targeting rule that matched, when reason is rule-match.

string
nullable

Responses

Section titled “ Responses ”

202

Section titled “ 202 ”

Events were accepted for processing.

400

Section titled “ 400 ”

The batch exceeds the maximum number of events per request.

Media type application/json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
key
additional properties

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

401

Section titled “ 401 ”

Client SDK key is missing or invalid.

Media type application/json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
key
additional properties

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

413

Section titled “ 413 ”

The request body is larger than this endpoint accepts.

Media type application/json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
key
additional properties

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}