No results for ""
  • Home
  • API docs


Building a metric import and sync integration

Read time: 4 minutes
Last edited: May 01, 2024


This guide explains how LaunchDarkly partners can use the REST API to build an integration for creating metrics. By the end of this guide, you as a LaunchDarkly partner should have the information you need to create an integration that can create metrics for our joint customers' LaunchDarkly experiments.

About LaunchDarkly metrics

Experimentation lets you validate the impact of features you roll out to your app or infrastructure. You can measure things like page views, clicks, load time, infrastructure costs, and more.

By connecting metrics you create to flags in your LaunchDarkly environment, you can measure the changes in your customer's behavior based on what flags they evaluate. This helps you make more informed decisions, so the features your development team ships align with your business objectives.

You can use this integration method to create either custom conversion/binary metrics or custom numeric metrics:

  • Custom conversion/binary metrics track events for any arbitrary event
  • Custom numeric metrics track increases or decreases in a numeric value against a baseline you set

To learn more, read Metric events.

Build an integration

To build an integration, make sure you meet the prerequisites. Then follow the steps outlined on the Getting started page.

The Getting started page explains each of the following steps in detail:

  1. Forking the LaunchDarkly Integration Framework repository.
  2. Creating a new directory.
  3. Creating an integration manifest.
  1. Defining the integration's capabilities.
  • No capability section is required for a metric creation integration. You can add a top-level key "otherCapabilities"" ["external"].
  1. Creating end-user documentation and README.
  2. Submitting the integration.

Format of a request

For a custom metric integration, the following sections describe the required request format.

HTTP User Agent for REST API requests

All API calls from LaunchDarkly partners should include a custom User-Agent:

{launchdarkly product}-{source product}-int/{version}


Your integration can use either API keys or OAuth for authentication:

  • If you use API keys, your customers will need to create them in LaunchDarkly and provide them to your service.
  • If you use OAuth, configure it as described in Registering a LaunchDarkly OAuth client.

LaunchDarkly has support for OAuth clients. The only two types of scoped permissions are currently reader and writer. A metric integration needs the writer scope so it can create metrics. However, your customers may not want to provide the level of access overall that this functionality would grant.

For a custom metric integration, we suggest that partners use an API key.


The endpoint to create a new metric accepts a POST body in JSON format. The minimum set of required parameters is:

  • key: The metric key.
  • kind: This kind of event your metric will track. This should be custom.
  • isNumeric: Whether to track numeric changes in value against a baseline (true) or to track a conversion when users taken an action (false).
  • unit: The unit of measure for numeric custom metrics.
  • eventKey: This should be equal to the event key you're using in your code.
Metric keys and event keys are different

LaunchDarkly automatically generates a metric key when you create a metric. You can use the metric key to identify the metric in API calls. To learn more, read Creating metrics.

Custom conversion/binary and custom numeric metrics also require an event key. You can set the event key to anything you want. Adding this event key to your codebase lets your SDK track actions customers take in your app as events. To learn more, read Sending custom events.

You can also use the REST API: Create a LaunchDarkly metric

Manifest.json example

This manifest is required for an integration. It renders your integration metadata inside of the LaunchDarkly UI.

"name": "Sample Integration",
"version": "1.0.0",
"overview": "Short one-liner describing your integration.",
"description": "Send flag data to space. Markdown-based description.",
"author": "Acme Inc.",
"supportEmail": "",
"links": {
"site": "",
"supportWebsite": "",
"privacyPolicy": ""
"categories": ["automation"],
"icons": {
"square": "assets/images/square.svg",
"horizontal": "assets/images/horizontal.svg"
"otherCapabilities": ["external"]


This guide describes the process of building a metric integration. To learn more about building your own integrations, read Building partner integrations.

Want to know more? Start a trial.

Your 14-day trial begins as soon as you sign up. Get started in minutes using the in-app Quickstart. You'll discover how easy it is to release, monitor, and optimize your software.

Want to try it out? Start a trial.