> ## Documentation Index
> Fetch the complete documentation index at: https://confidence.spotify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Metrics to a Surface

> Learn how to add required and associated metrics to a surface using the API.

export const HowToSchema = ({name, description, steps = []}) => {
  const schema = {
    "@context": "https://schema.org",
    "@type": "HowTo",
    name,
    description
  };
  if (steps.length > 0) {
    schema.step = steps.map((s, i) => ({
      "@type": "HowToStep",
      position: i + 1,
      name: typeof s === "string" ? s : s.name,
      text: typeof s === "string" ? s : s.text || s.name
    }));
  }
  return <script type="application/ld+json" dangerouslySetInnerHTML={{
    __html: JSON.stringify(schema)
  }} />;
};

<HowToSchema
  name="Add Metrics to a Surface"
  description="Learn how to add required and associated metrics to a surface using the API."
  steps={[
{
  name: "Add a Required Metric",
  text: "Confidence enforces required metrics for all experiments on the surface. Use the following to add a required metric metrics/ to a surface with resource name surfaces/: The preferredDirection can be INCREASE or DECREASE, indicating which direction the metric should move in for a successful experiment.",
},
{
  name: "Add an Associated Metric",
  text: "Confidence suggests associated metrics for experiments on the surface but doesn't enforce them. Use the following to add an associated metric:",
},
]}
/>

Add [metrics to a surface](/docs/surfaces/surface-settings#metrics) to make them easier to find for experimenters, or enforce that all experiments on the surface check this metric for regressions.

## Add a Required Metric

Confidence enforces required metrics for all experiments on the surface. Use the following to add a required metric `metrics/<metric>` to a surface with resource name `surfaces/<surface>`:

```bash theme={null}
curl -X PATCH "https://workflow.confidence.dev/v1/surfaces/<surface>?updateMask=metricConfig.mandatoryMetrics" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metricConfig": {
      "mandatoryMetrics": [{
        "metric": "metrics/<metric>",
        "guardrailMetric": {},
        "preferredDirection": "INCREASE"
      }]
    }
  }'
```

The `preferredDirection` can be `INCREASE` or `DECREASE`, indicating which direction the metric should move in for a successful experiment.

## Add an Associated Metric

Confidence suggests associated metrics for experiments on the surface but doesn't enforce them. Use the following to add an associated metric:

```bash theme={null}
curl -X PATCH "https://workflow.confidence.dev/v1/surfaces/<surface>?updateMask=metricConfig.associatedMetrics" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metricConfig": {
      "associatedMetrics": [{
        "metric": "metrics/<metric>"
      }]
    }
  }'
```

## Related Resources

<CardGroup cols={2}>
  <Card title="Add Metrics to Surface" href="/docs/how-to-guides/add-metrics-to-surface">
    Console guide for adding metrics
  </Card>

  <Card title="Surface Settings Reference" href="/docs/surfaces/surface-settings">
    Deep dive into surface configuration
  </Card>

  <Card title="Create Metrics API" href="/docs/api/how-to-guides/metrics/create-metric">
    API reference for creating metrics
  </Card>
</CardGroup>