> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://docs.paid.ai/v-2/llms.txt
> - v1: https://docs.paid.ai/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paid.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paid.ai/_mcp/server.

# Get current value model

GET https://api.agentpaid.io/api/v2/value-models/

Returns the current (latest active) value model for the organization.

Reference: https://docs.paid.ai/api-reference/api-reference/value-models/get-current-value-model

## Authentication

- `Authorization` header (bearer token, required) — API Key authentication using Bearer token

## Response

### 200

200

- `id` (string, required) — Value model version ID.
- `version` (integer, required) — Monotonically increasing version number.
- `content` (ValueModelContent, required) — Full value model configuration: value types, formulas, events, overrides, and actions.
- `createdAt` (datetime, required)
- `activatedAt` (datetime, required, nullable)
- `effectiveFrom` (datetime, required, nullable)
- `effectiveTo` (datetime, required, nullable)

## Errors

### 404 Not Found Error

404

- `error` (string, required)
- `code` (string, optional)
- `details` (string, optional)

### 500 Internal Server Error

500

- `error` (string, required)
- `code` (string, optional)
- `details` (string, optional)

## Types

### ValueModelContent

Full value model configuration: value types, formulas, events, overrides, and actions.

- `currency` (string, required)
- `valueTypes` (list of ValueModelContentValueTypesItems, required)
- `formulas` (list of ValueModelContentFormulasItems, required)
- `signals` (list of ValueModelContentSignalsItems, required)
- `segmentTables` (list of ValueModelContentSegmentTablesItems, optional)
- `overrides` (list of ValueModelContentOverridesItems, optional)
- `groupingKeys` (list of ValueModelContentGroupingKeysItems, optional)
- `flows` (list of ValueModelContentFlowsItems, optional)
- `actions` (list of ValueModelContentActionsItems, optional)

### ValueModelContentValueTypesItems

- `slug` (string, required)
- `name` (string, required)
- `calculationTimeline` (list of ValueModelContentValueTypesItemsCalculationTimelineItems, required)
- `description` (string, optional, nullable)
- `longDescription` (string, optional, nullable)
- `sources` (list of ValueModelContentValueTypesItemsSourcesItems, optional, nullable)
- `maturation` (ValueModelContentValueTypesItemsMaturation, optional, nullable) — Gates when this value type's number is published to a customer on a value receipt. Evaluated per customer, cumulative since their first signal for this value type, as of the receipt's end date. Until the threshold is met the receipt withholds the figure and shows a 'gathering data' state instead. At least one of minDataPoints or minMonths is required.
- `displayOrder` (integer, optional, nullable)
- `color` (string, optional, nullable)
- `icon` (string, optional, nullable)
- `category` (enum, optional)
  - Allowed values: `hve`, `time`, `cost`, `revenue`, `risk`
- `archivedAt` (datetime, optional, nullable)

### ValueModelContentFormulasItems

- `id` (string, required)
- `valueTypeSlug` (string, required)
- `label` (string, required)
- `variables` (list of ValueModelContentFormulasItemsVariablesItems, required)
- `expression` (string, required)
- `description` (string, optional)
- `conditions` (list of ValueModelContentFormulasItemsConditionsItems, optional)
- `defaultResult` (ValueModelContentFormulasItemsDefaultResult, optional)

### ValueModelContentSignalsItems

- `eventName` (string, required)
- `label` (string, required)
- `formulaId` (string, optional)
- `variableMapping` (map from string to string, optional)
- `defaults` (map from string to ValueModelContentSignalsItemsDefaults, optional)
- `segmentTableIds` (list of string, optional)
- `description` (string, optional)
- `labels` (list of string, optional)
- `tags` (list of string, optional)

### ValueModelContentSegmentTablesItems

- `id` (string, required)
- `label` (string, required)
- `segmentKeys` (list of string, required)
- `columns` (list of ValueModelContentSegmentTablesItemsColumnsItems, required)
- `rows` (list of ValueModelContentSegmentTablesItemsRowsItems, required)
- `defaultRow` (map from string to double, optional)

### ValueModelContentOverridesItems

- `id` (string, required)
- `label` (string, required)
- `scope` (ValueModelContentOverridesItemsScope, required)
- `currency` (string, optional)
- `valueTypeOverrides` (map from string to ValueModelContentOverridesItemsValueTypeOverrides, optional) — Per-value-metric formula variable overrides, keyed by value type slug. Scoped to the named metric's formulas only, so a binding event shared with other metrics does not leak these values into them.
- `additionalSignals` (list of ValueModelContentOverridesItemsAdditionalSignalsItems, optional)
- `monetaryConversionOverrides` (map from string to ValueModelContentOverridesItemsMonetaryConversionOverrides, optional)

### ValueModelContentGroupingKeysItems

- `id` (string, required)
- `field` (string, required)
- `displayName` (string, required)

### ValueModelContentFlowsItems

- `id` (string, required)
- `name` (string, required)
- `groupingKeyId` (string, required)
- `value` (string, required)
- `completionEventName` (string, optional)
- `runNoun` (string, optional)
- `runNameField` (string, optional) — The signal metadata field whose value names each run of this flow, such as candidate_name. A run takes the newest non-blank value among its signals. Without one, the run takes the title of its completion action, then its run noun and run ID. Must differ from the grouping key field.

### ValueModelContentActionsItems

- `eventName` (string, required) — Event type for this organization-wide action.
- `name` (string, required)
- `fields` (list of ValueModelContentActionsItemsFieldsItems, required) — Display fields in their presentation order.

### ValueModelContentValueTypesItemsCalculationTimelineItems

- `effectiveFrom` (datetime, required)
- `calculation` (ValueModelContentValueTypesItemsCalculationTimelineItemsCalculation, required)

### ValueModelContentValueTypesItemsSourcesItems

- `name` (string, required)
- `url` (string, required)

### ValueModelContentValueTypesItemsMaturation

Gates when this value type's number is published to a customer on a value receipt. Evaluated per customer, cumulative since their first signal for this value type, as of the receipt's end date. Until the threshold is met the receipt withholds the figure and shows a 'gathering data' state instead. At least one of minDataPoints or minMonths is required.

### ValueModelContentFormulasItemsVariablesItems

- `id` (string, required)
- `label` (string, required)
- `type` (enum, optional, default: number)
  - Allowed values: `number`, `string`, `boolean`, `duration`
- `description` (string, optional)
- `format` (enum, optional) — Display-only formatting hint. "percent" renders the variable as a percentage (a stored 0.02 displays as 2%). "duration" renders it as a length of time, stepping down to the largest whole unit (0.75 with formatUnit "hours" displays as "45 minutes") and requires formatUnit. Calculations always use the stored raw value.
  - Allowed values: `percent`, `duration`
- `formatUnit` (enum, optional) — The time unit the stored value is expressed in. Required when format is "duration"; ignored otherwise.
  - Allowed values: `seconds`, `minutes`, `hours`, `days`
- `derivedFrom` (ValueModelContentFormulasItemsVariablesItemsDerivedFrom, optional)

### ValueModelContentFormulasItemsConditionsItems

- `field` (string, required)
- `operator` (enum, required)
  - Allowed values: `gte`, `gt`, `lt`, `lte`, `eq`, `neq`, `contains`, `eq_string`, `eq_bool`
- `value` (ValueModelContentFormulasItemsConditionsItemsValue, required)
- `result` (ValueModelContentFormulasItemsConditionsItemsResult, required)

### ValueModelContentFormulasItemsDefaultResult

- `type` (enum, required)
  - Allowed values: `constant`, `expression`
- `value` (double, optional)
- `expression` (string, optional)

### ValueModelContentSignalsItemsDefaults

### ValueModelContentSegmentTablesItemsColumnsItems

- `variableId` (string, required)
- `label` (string, required)
- `type` (enum, required)
  - Allowed values: `number`

### ValueModelContentSegmentTablesItemsRowsItems

- `segmentValues` (map from string to string, required)
- `variables` (map from string to double, required)

### ValueModelContentOverridesItemsScope

- `customerIds` (list of string, required)

### ValueModelContentOverridesItemsValueTypeOverrides

- `variables` (map from string to ValueModelContentOverridesItemsValueTypeOverridesVariables, optional) — Formula variable values to apply for this scope's customers, keyed by variable id. Each key must be a variable declared by one of this value type's formulas.

### ValueModelContentOverridesItemsAdditionalSignalsItems

- `eventName` (string, required)
- `label` (string, required)
- `formulaId` (string, optional)
- `variableMapping` (map from string to string, optional)
- `defaults` (map from string to ValueModelContentOverridesItemsAdditionalSignalsItemsDefaults, optional)
- `segmentTableIds` (list of string, optional)
- `description` (string, optional)
- `labels` (list of string, optional)
- `tags` (list of string, optional)

### ValueModelContentOverridesItemsMonetaryConversionOverrides

- `variables` (map from string to double, optional)

### ValueModelContentActionsItemsFieldsItems

- `key` (string, required) — Exact metadata key. Credit history supports keys without dots.
- `label` (string, required)
- `type` (enum, required)
  - Allowed values: `text`, `link`
- `description` (string, optional) — What the value of this field means.
- `isTitle` (boolean, optional) — Also show this field in the event headline.
- `hidden` (boolean, optional) — No reader shows this field. It keeps its label and description. Absent means shown.

### ValueModelContentValueTypesItemsCalculationTimelineItemsCalculation

- `unit` (ValueModelContentValueTypesItemsCalculationTimelineItemsCalculationUnit, required)
- `formulaIds` (list of string, required)
- `signalEventNames` (list of string, required)
- `segmentTableIds` (list of string, required)
- `overrideIds` (list of string, required)
- `monetaryConversion` (ValueModelContentValueTypesItemsCalculationTimelineItemsCalculationMonetaryConversion, optional)

### ValueModelContentFormulasItemsVariablesItemsDerivedFrom

- `sourceField` (string, required)
- `targetUnit` (enum, required)
  - Allowed values: `seconds`, `minutes`, `hours`, `days`
- `sourceUnit` (enum, optional) — Fixed source unit the signal field reports its value in; the engine converts it into the metric's duration unit (targetUnit). Used as the fallback when sourceUnitFromSignal is set but the companion field is missing/invalid. Requires a duration value type.
  - Allowed values: `seconds`, `minutes`, `hours`, `days`
- `sourceUnitFromSignal` (boolean, optional) — When true, each event names its own source unit in a "\<sourceField>\_unit" companion field (e.g. sourceField "time\_spent" reads "time\_spent\_unit"), which must be one of seconds|minutes|hours|days. Takes precedence over sourceUnit; if the companion is absent or invalid it falls back to sourceUnit. If neither resolves, the payload value is discarded and the variable's default is used (the default is stored in the metric's unit and is never converted); the value is never silently treated as seconds. Requires a duration value type.

### ValueModelContentFormulasItemsConditionsItemsValue

### ValueModelContentFormulasItemsConditionsItemsResult

- `type` (enum, required)
  - Allowed values: `constant`, `expression`
- `value` (double, optional)
- `expression` (string, optional)

### ValueModelContentOverridesItemsValueTypeOverridesVariables

### ValueModelContentOverridesItemsAdditionalSignalsItemsDefaults

### ValueModelContentValueTypesItemsCalculationTimelineItemsCalculationUnit

### ValueModelContentValueTypesItemsCalculationTimelineItemsCalculationMonetaryConversion

- `expression` (string, required)
- `variables` (list of ValueModelContentValueTypesItemsCalculationTimelineItemsCalculationMonetaryConversionVariablesItems, optional)
- `conditions` (list of ValueModelContentValueTypesItemsCalculationTimelineItemsCalculationMonetaryConversionConditionsItems, optional)

### ValueModelContentValueTypesItemsCalculationTimelineItemsCalculationMonetaryConversionVariablesItems

- `id` (string, required)
- `label` (string, required)
- `default` (double, required)

### ValueModelContentValueTypesItemsCalculationTimelineItemsCalculationMonetaryConversionConditionsItems

- `field` (string, required)
- `operator` (enum, required)
  - Allowed values: `gte`, `gt`, `lt`, `lte`, `eq`, `neq`, `contains`, `eq_string`, `eq_bool`
- `value` (ValueModelContentValueTypesItemsCalculationTimelineItemsCalculationMonetaryConversionConditionsItemsValue, required)
- `result` (ValueModelContentValueTypesItemsCalculationTimelineItemsCalculationMonetaryConversionConditionsItemsResult, required)

### ValueModelContentValueTypesItemsCalculationTimelineItemsCalculationMonetaryConversionConditionsItemsValue

### ValueModelContentValueTypesItemsCalculationTimelineItemsCalculationMonetaryConversionConditionsItemsResult

- `type` (enum, required)
  - Allowed values: `constant`, `expression`
- `value` (double, optional)
- `expression` (string, optional)

## Examples

**Response**

```json
{
  "id": "string",
  "version": 3,
  "content": {
    "currency": "string",
    "valueTypes": [
      {
        "slug": "string",
        "name": "string",
        "calculationTimeline": [
          {
            "effectiveFrom": "2024-01-15T09:30:00Z",
            "calculation": {
              "unit": {
                "type": "monetary"
              },
              "formulaIds": [
                "string"
              ],
              "signalEventNames": [
                "string"
              ],
              "segmentTableIds": [
                "string"
              ],
              "overrideIds": [
                "string"
              ],
              "monetaryConversion": {
                "expression": "string",
                "variables": [
                  {
                    "id": "string",
                    "label": "string",
                    "default": 1.1
                  }
                ],
                "conditions": [
                  {
                    "field": "string",
                    "operator": "gte",
                    "value": 1.1,
                    "result": {
                      "type": "constant",
                      "value": 1.1,
                      "expression": "string"
                    }
                  }
                ]
              }
            }
          }
        ],
        "description": "string",
        "longDescription": "string",
        "sources": [
          {
            "name": "string",
            "url": "string"
          }
        ],
        "maturation": null,
        "displayOrder": 1,
        "color": "string",
        "icon": "string",
        "category": "hve",
        "archivedAt": "2024-01-15T09:30:00Z"
      }
    ],
    "formulas": [
      {
        "id": "string",
        "valueTypeSlug": "string",
        "label": "string",
        "variables": [
          {
            "id": "string",
            "label": "string",
            "type": "number",
            "description": "string",
            "format": "percent",
            "formatUnit": "seconds",
            "derivedFrom": {
              "sourceField": "string",
              "targetUnit": "seconds",
              "sourceUnit": "seconds",
              "sourceUnitFromSignal": true
            }
          }
        ],
        "expression": "string",
        "description": "string",
        "conditions": [
          {
            "field": "string",
            "operator": "gte",
            "value": 1.1,
            "result": {
              "type": "constant",
              "value": 1.1,
              "expression": "string"
            }
          }
        ],
        "defaultResult": {
          "type": "constant",
          "value": 1.1,
          "expression": "string"
        }
      }
    ],
    "signals": [
      {
        "eventName": "string",
        "label": "string",
        "formulaId": "string",
        "variableMapping": {},
        "defaults": {},
        "segmentTableIds": [
          "string"
        ],
        "description": "string",
        "labels": [
          "string"
        ],
        "tags": [
          "string"
        ]
      }
    ],
    "segmentTables": [
      {
        "id": "string",
        "label": "string",
        "segmentKeys": [
          "string"
        ],
        "columns": [
          {
            "variableId": "string",
            "label": "string",
            "type": "number"
          }
        ],
        "rows": [
          {
            "segmentValues": {},
            "variables": {}
          }
        ],
        "defaultRow": {}
      }
    ],
    "overrides": [
      {
        "id": "string",
        "label": "string",
        "scope": {
          "customerIds": [
            "string"
          ]
        },
        "currency": "string",
        "valueTypeOverrides": {},
        "additionalSignals": [
          {
            "eventName": "string",
            "label": "string",
            "formulaId": "string",
            "variableMapping": {},
            "defaults": {},
            "segmentTableIds": [
              "string"
            ],
            "description": "string",
            "labels": [
              "string"
            ],
            "tags": [
              "string"
            ]
          }
        ],
        "monetaryConversionOverrides": {}
      }
    ],
    "groupingKeys": [
      {
        "id": "string",
        "field": "string",
        "displayName": "string"
      }
    ],
    "flows": [
      {
        "id": "string",
        "name": "string",
        "groupingKeyId": "string",
        "value": "string",
        "completionEventName": "string",
        "runNoun": "string",
        "runNameField": "string"
      }
    ],
    "actions": [
      {
        "eventName": "string",
        "name": "string",
        "fields": [
          {
            "key": "string",
            "label": "string",
            "type": "text",
            "description": "string",
            "isTitle": true,
            "hidden": true
          }
        ]
      }
    ]
  },
  "createdAt": "2024-01-15T09:30:00Z",
  "activatedAt": "2024-01-15T09:30:00Z",
  "effectiveFrom": "2024-01-15T09:30:00Z",
  "effectiveTo": "2024-01-15T09:30:00Z"
}
```

**SDK Code**

```python
import requests

url = "https://api.agentpaid.io/api/v2/value-models/"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.agentpaid.io/api/v2/value-models/';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentpaid.io/api/v2/value-models/"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.agentpaid.io/api/v2/value-models/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.agentpaid.io/api/v2/value-models/")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.agentpaid.io/api/v2/value-models/', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.agentpaid.io/api/v2/value-models/");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentpaid.io/api/v2/value-models/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```