Reporting

The POST/report endpoint allows you to report usage data to Tggl from your server, proxy, and clients. You can then find this data directly in the Tggl dashboard to track which flags are being used, how often, by which client...

curl 'https://api.tggl.io/report' \
  -H 'Content-Type: application/json' \
  -H 'x-tggl-api-key: <api key>' \
  --data-raw '{}'

The body should be a JSON object with the properties you want to report as described in the following sections.

Flag evaluation

Both client and server keys can be used to report flag evaluation metrics. You can add a clients array to the body to report metrics:

JSON body

cURL

{
  "clients": [
    {
      "flags": {}
    }
  ]
}

You may pass multiple clients at once and add an id for each client to identify them in the dashboard:

{
  "clients": [
    {
      "id": "react-client:1.3.2",
      "flags": {}
    },
    {
      "id": "php-client:2.1.0",
      "flags": {}
    }
  ]
}

For each client, you can specify which flags were evaluated and the result of those evaluations. The flags object should contain the flag key as the key and an array of evaluation results as the value:

{
  "clients": [
    {
      "id": "react-client:1.3.2",
      "flags": {
        "new-button-color": [
          { "value": "#ff0000", "active": true, "count": 3 },
          { "value": "#00ff00", "active": true, "count": 7 },
          { "active": false, "count": 42 }
        ],
        "analytics-panel-beta": [
          { "active": true, "count": 11 },
          { "active": false, "count": 35 }
        ]
      }
    }
  ]
}

Each flag evaluation result is an object where all keys are optional and follows the following schema:

Schema

YAML

JSON

TypeScript

FlagEvaluationResult object

active boolean

The only require key, true when the flag was evaluated as active.

value any

The value the flag was evaluated to. Can by any type. Should be omitted if the flag was evaluated as inactive.

default any

The default value that was used in the code. Can by any type. Can be omitted if the flag was simply checked for its active state and not its value.

count integer

The number of times the flag was evaluated to that specific value. Default to 1 if not specified.

Context

Only the server API key can be used to report context related metrics. You can report both the properties you received for each context, and the values each of those properties had.

Received properties

You can add a receivedProperties object to the body of the request to report the properties you received for each context:

JSON body

cURL

{
  "receivedProperties": {
    "userId": [1721461881, 1721461898],
    "email": [1721461881, 1721461898]
  }
}

The keys of the receivedProperties object are the properties you received, and the values are a tuple of two timestamps in seconds (not milliseconds) that represent the first and last time each property was received.

Received values

You can add a receivedValues object to the body of the request to report the values you received for each property:

JSON body

cURL

{
  "receivedValues": {
    "email": [
      ["elon@gmail.com"],
      ["jeff@gmail.com"]
    ]
  }
}

The keys of the receivedValues object are the properties, and the values are an array of received values. Each received value is a tuple of the value itself, and an optional label associated.

For instance, if you want to associate a user's name to its user ID, you can do so like this:

{
  "receivedValues": {
    "userId": [
      ["U4zZSgiR", "Elon Musk"],
      ["Be6QkIjN", "Jeff Bezos"]
    ]
  }
}

PreviousGet flags config