• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
    No results for ""


    Importing metric events

    Read time: 2 minutes
    Last edited: Jan 04, 2023


    This topic explains how to import metric events from your existing data pipeline for use with Experimentation. Using the metric import REST API described below, you can send your already-instrumented metrics into LaunchDarkly and use them in experiments, without writing and deploying new code for each metric.

    This feature is for Early Access Program customers only

    The metric import API is only available to members of LaunchDarkly's Early Access Program (EAP). If you want access to this feature, join the EAP.

    Segment customers should use the Segment integration

    If the metric events you want to use with Experimentation are already flowing through Segment, consider using our Segment Experimentation integration instead.

    This feature is in beta

    Development work on the metric import API is ongoing. Elements of the metric import API may change without notice, including becoming backwards incompatible.

    API details

    Here's how to structure your import metric request:

    Request elementDescription
    Base URLhttps://events.launchdarkly.com

    Replace YOUR_CLIENT_SIDE_ID with the client-side ID for the environment your metric events pertain to. Your client-side ID is available under Environments on the Projects tab on the Account settings page.
    REST methodPOST
    • Content-Type: application/json, required
    • X-LaunchDarkly-Event-Schema: 4, required
    • LD-API-Version: beta, required
    • X-LaunchDarkly-Payload-ID: YOUR_PAYLOAD_ID, optional. Use this to send a unique ID for the payload, which you can use to retry failed requests.
    Request bodyThe events to import, represented as a JSON array.

    Request body format

    The request body must consist of a JSON array of custom events.

    Each custom event is a JSON object with the following shape:

    "kind": "custom",
    "key": "custom-metric",
    "creationDate": 16420388151234,
    "metricValue": 32.0,
    "contextKeys": {
    "user": "jim",

    Here are the details of each custom event field:

    Custom event fieldDescription
    kindA string, must be set to custom.
    keyIdentifies your metric. When you create your metric in LaunchDarkly, its Event name must exactly match this value. To learn more, read Creating metrics.
    creationDateTimestamp of when the event is created, in Unix milliseconds.
    metricValueThe value of the metric. For numeric metrics, this is required. For conversion metrics, this is optional and LaunchDarkly will ignore it if provided.
    contextKeysA JSON object with a single property, named user. The value of the user property is the user key and must uniquely identify the user that the metric is about. The user key must exactly match the user key provided to any LaunchDarkly SDKs evaluating flags that will be used in the experiments.


    Here is an example curl invocation that sends two metric events for different users to the same metric. Replace YOUR_CLIENT_SIDE_ID with your client-side ID.

    curl -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'LD-API-Version: beta' \
    -H 'X-LaunchDarkly-Event-Schema: 4' \
    -d '[{"kind":"custom","contextKeys":{"user":"bob"},"creationDate":1638561938594,"key":"Degree of awesomeness","metricValue": 11.0},{"kind":"custom","contextKeys":{"user":"alice"},"creationDate":1638561938594,"key":"Degree of awesomeness","metricValue": 6.0}]' \

    Responses and error handling

    Clients should expect to receive the following response status codes from the API:

    Response status codeDescription
    202 Accepted The request completed successfully and the metric events were accepted for import. Note that they may still not be recorded if their format does not confirm to the required JSON schema. To learn more, read Known limitations.
    400 Bad Request The request body is not valid UTF-8.
    403 Forbidden Your account does not have access to the metric import API, or the LD-API-Version header is not set to beta.
    404 Not Found The clientSideID specified in the URL is invalid.
    406 Not Acceptable The X-LaunchDarkly-Event-Schema header is not set to 4.
    429 Too Many Requests LaunchDarkly has recently received a very large volume of traffic from your account.
    5xx The metric import API is temporarily unavailable. In this case the metric events may not have been accepted for import.

    4xx error responses, with the exception of 404 Not Found, have bodies in JSON format describing the reason for the error.

    5xx error responses should be rare, and indicate the metrics may not have been accepted for import. To learn more, read Retrying failed requests.

    Known limitations

    Because the metric import API is still in beta, there are a few known limitations. These include the following:

    • There is a limit on the request body size of 10MB per request. If you need to batch-upload a large number of historical events, please contact us for more information.
    • The API does not validate that request bodies conform to the required JSON schema. Invalid request bodies, or JSON objects within a request body that do not conform to the schema, will not be processed.
    • Metric events imported via the metric import API will not appear in the Debugger in the LaunchDarkly UI.

    Best practices

    Batching events

    If possible, for efficiency, clients should send batches of events in each request, rather than making a separate request per event. For example, consider time-based batches sent once per minute. Clients are free to choose their own batch size, but the request body must be smaller than 10MB in total.

    Retrying failed requests

    Clients should not retry requests receiving 4xx responses, with the exception of 429 Too Many Requests.

    429 and 5xx responses indicate transient issues, so it is appropriate to retry requests receiving these responses, in order to ensure that their events are accepted for import. Clients that retry requests must follow these instructions when doing so:

    • Clients must not retry immediately, but must back off, preferably with an exponentially increasing delay.
    • To ensure events are only processed once when retrying, all requests must include the X-LaunchDarkly-Payload-ID header. This header must contain a freshly generated payload id for each request. However, when retrying, the retries must reuse the same payload id as the original request. LaunchDarkly will use this header to deduplicate repeated requests and ensure events are only processed once.

    Billing implications

    While the metric import API is in Early Access, there is no separate charge for importing metric events.

    However, imported events may count toward usage of the following features:

    • If the imported events are recorded in an experiment and you are on an older contract that bills by Experimentation events, then the imported events may count toward Experimentation usage. This does not apply to the current Experimentation billing model introduced in 2022, which is based on unique user keys.
    • Imported events will be included in the Data Export, and count toward Data Export usage.