Metrics API

Create, access, and update product metrics with the Metrics API.

Deleting Metrics

You can create, read, and update metrics via API, but deleting metrics must be done through the dashboard.

Endpoints

GET/v1/products/:id_or_slug/metrics

List metrics

Returns all metric definitions for a product.

POST/v1/products/:id_or_slug/metrics

Create metric

Creates a new metric definition.

GET/v1/products/:id_or_slug/metrics/:key/values

Get metric values

Returns historical values for a metric.

PUT/v1/products/:id_or_slug/metrics/:key/value

Set metric value

Sets a metric value (overwrites existing).

PATCH/v1/products/:id_or_slug/metrics/:key/value

Adjust metric value

Adjusts a metric value by a delta (increase or decrease).

Metric Types

Metrics in MyOpcs come in two types, each with different behavior:

timeseries

Time-series data with one data point per day. Examples: daily active users, page views, signups. Each date has its own value.

snapshot

Cumulative or current state values. Examples: total users, total revenue. Represents a point-in-time measurement.

Metric Definition Object

The metric definition contains metadata about a metric.

Attribute	Type	Description
`id`	string	Unique identifier for the metric definition
`key`	string	API identifier (e.g., daily_active_users)
`name`	string	Display name (e.g., Daily Active Users)
`type`	string	One of: timeseries, snapshot
`unit`	string \| null	Unit of measurement (e.g., %, $, users)
`description`	string \| null	Description of the metric
`createdAt`	string	ISO 8601 timestamp of creation
`updatedAt`	string	ISO 8601 timestamp of last update

Metric Value Object

A metric value represents a single data point.

Attribute	Type	Description
`id`	string	Unique identifier for the metric value
`date`	string	Date of the data point (YYYY-MM-DD)
`value`	number	The metric value
`createdAt`	string	ISO 8601 timestamp of creation

GET

List Metrics

Returns all metric definitions for a product, including the latest value for each.

Request

Bash

curl https://api.myopcs.com/api/v1/products/my-saas-app/metrics \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{}JSON

{
  "data": [
    {
      "id": "metric_abc123",
      "key": "daily_active_users",
      "name": "Daily Active Users",
      "type": "timeseries",
      "unit": "users",
      "description": "Number of unique users per day",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:45:00Z",
      "latestValue": {
        "id": "value_xyz",
        "date": "2024-01-20",
        "value": 1250,
        "createdAt": "2024-01-20T08:00:00Z"
      }
    }
  ]
}

POST

Create Metric

Creates a new metric definition for a product. The key must be unique within the product.

Request

Bash

curl -X POST https://api.myopcs.com/api/v1/products/my-saas-app/metrics \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "monthly_recurring_revenue",
    "name": "Monthly Recurring Revenue",
    "type": "snapshot",
    "unit": "$",
    "description": "Total MRR"
  }'

Body Parameters

Parameter	Type	Required	Description
`key`	string	Yes	API identifier (lowercase letters, numbers, underscores, hyphens)
`name`	string	Yes	Display name for the metric
`type`	string	No	One of: timeseries (default), snapshot
`unit`	string	No	Unit of measurement (e.g., %, $, users)
`description`	string	No	Description of the metric

Response

{}JSON

{
  "data": {
    "id": "metric_new123",
    "key": "monthly_recurring_revenue",
    "name": "Monthly Recurring Revenue",
    "type": "snapshot",
    "unit": "$",
    "description": "Total MRR",
    "createdAt": "2024-01-21T10:00:00Z",
    "updatedAt": "2024-01-21T10:00:00Z"
  }
}

GET

Get Metric Values

Returns values for a specific metric. For timeseries metrics, returns historical data points within the date range. For snapshot metrics, returns a single current value.

Request (timeseries)

Bash

curl "https://api.myopcs.com/api/v1/products/my-saas-app/metrics/daily_active_users/values?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

Request (snapshot)

Bash

curl "https://api.myopcs.com/api/v1/products/my-saas-app/metrics/total_users/values" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Type	Required	Description
`startDate`	string	No	Start date filter (YYYY-MM-DD)
`endDate`	string	No	End date filter (YYYY-MM-DD)

Response

{}JSON

{
  "data": [
    {
      "id": "value_001",
      "date": "2024-01-01",
      "value": 1000,
      "createdAt": "2024-01-01T08:00:00Z"
    },
    {
      "id": "value_002",
      "date": "2024-01-02",
      "value": 1050,
      "createdAt": "2024-01-02T08:00:00Z"
    }
  ],
  "metric": {
    "id": "metric_abc123",
    "key": "daily_active_users",
    "name": "Daily Active Users",
    "type": "timeseries"
  }
}

PUT

Set Metric Value

Sets a metric value. This overwrites any existing value. Behavior differs by type: timeseries requires date, snapshot ignores date.

timeseries: date is required. Sets the value for that specific date.

snapshot: date is ignored. Updates the current value.

Request (timeseries)

Bash

curl -X PUT https://api.myopcs.com/api/v1/products/my-saas-app/metrics/daily_active_users/value \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2024-01-21",
    "value": 1300
  }'

Request (snapshot)

Bash

curl -X PUT https://api.myopcs.com/api/v1/products/my-saas-app/metrics/total_users/value \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 15500
  }'

Body Parameters

Parameter	Type	Required	Description
`date`	string	No	Date for the value (YYYY-MM-DD). Required for timeseries, optional for snapshot
`value`	number	Yes	The value to set (will overwrite existing value)

Response

{}JSON

{
  "data": {
    "id": "value_new",
    "date": "2024-01-21",
    "value": 1300,
    "createdAt": "2024-01-21T10:00:00Z"
  }
}

PATCH

Adjust Metric Value

Adjusts a metric value by a delta (positive to increase, negative to decrease). Behavior differs by type: timeseries requires date, snapshot ignores date.

timeseries: date is required. Adjusts the value for that specific date.

snapshot: date is ignored. Adjusts the current value.

Request (snapshot - increase)

Bash

curl -X PATCH https://api.myopcs.com/api/v1/products/my-saas-app/metrics/total_users/value \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "delta": 100
  }'

Request (timeseries - decrease)

Bash

curl -X PATCH https://api.myopcs.com/api/v1/products/my-saas-app/metrics/daily_active_users/value \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2024-01-21",
    "delta": -50
  }'

Body Parameters

Parameter	Type	Required	Description
`date`	string	No	Date for the value (YYYY-MM-DD). Required for timeseries, optional for snapshot
`delta`	number	Yes	Amount to adjust (positive to increase, negative to decrease)

Response

{}JSON

{
  "data": {
    "id": "value_xyz",
    "date": "2024-01-21",
    "value": 15500,
    "createdAt": "2024-01-21T10:00:00Z"
  },
  "previousValue": 15400
}