Metrics & Dividends

Returns dividend data, returns, profitability, growth, leverage, and business quality metrics for a single asset symbol.

This endpoint retrieves a focused set of financial and market metrics for a single asset symbol, covering dividend data, historical returns, profitability, growth, leverage, and business quality indicators. 

Asset Type Compatibility

Primarily applicable to stocks. For ETFs and mutual funds, fundamental and profitability fields are generally not applicable and are returned as null.

When to Use This Endpoint

  • Retrieve dividend data, historical returns, and risk metrics for a single asset symbol.
  • Assess profitability, growth, leverage, and business quality indicators for stocks.
  • Access a consolidated set of financial metrics without retrieving a full data snapshot.

Request Parameters

POST
v1/metrics
symbol stringrequired

Asset identifier (ticker symbol).

tag stringoptional

User-defined identifier for the task (max 255 characters).

It is returned in the response data object, allowing you to match results with the corresponding request. It does not affect API processing or filtering logic.

Example Request
curl --location "https://api.finimpulse.com/v1/metrics" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <API_TOKEN>" \
  -d '{
      "symbol": "NVDA",
      "tag": "just tag"
  }'
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var client = new HttpClient();
var url = "https://api.finimpulse.com/v1/metrics";

client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var json = @"{
    ""symbol"": ""NVDA"",
    ""tag"": ""just tag""
}";
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync(url, content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.finimpulse.com/v1/metrics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Authorization: Bearer <API_TOKEN>"
  ],
  CURLOPT_POSTFIELDS => json_encode(
[
      "symbol" => "NVDA",
      "tag" => "just tag"
    ]
  )
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;
import urllib.request
import json

url = "https://api.finimpulse.com/v1/metrics"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API_TOKEN>"
}
data = {
    "symbol": "NVDA",
    "tag": "just tag"
}

req = urllib.request.Request(url,
    data=json.dumps(data).encode("utf-8"),
    headers=headers,
    method="POST")

with urllib.request.urlopen(req) as response:
    result = json.loads(response.read().decode("utf-8"))
    print(result)
const https = require('https');

const data = JSON.stringify({
    "symbol": "NVDA",
    "tag": "just tag"
});

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <API_TOKEN>',
    'Content-Length': Buffer.byteLength(data)
  }
};

const req = https.request('https://api.finimpulse.com/v1/metrics', options, (res) => {
  let body = '';
  res.on('data', chunk => body += chunk);
  res.on('end', () => console.log(JSON.stringify(JSON.parse(body), null, 2)));
});

req.on('error', (e) => console.error(e));
req.write(data);
req.end();

Response

The response returns a single object for the requested symbol.

Identification Fields

symbol string

Asset identifier (ticker symbol).

Dividends & Yield

dividend_rate number

Forward dividend rate.

dividend_rate_usd number

Forward dividend rate normalized to USD.

dividend_yield number

Forward dividend yield.

trailing_annual_dividend_rate number

Trailing 12-month dividend rate.

trailing_annual_dividend_rate_usd number

Trailing 12-month dividend rate normalized to USD.

trailing_annual_dividend_yield number

Trailing 12-month dividend yield.

Returns & Performance

one_year_return number

Total return over the past year.

three_year_return number

Total return over the past three years.

Technical Indicators

fifty_day_average_change_percent number

Percent difference vs 50-day average.

two_hundred_day_average_change_percent number

Percent difference vs 200-day average.

Profitability & Margins

free_cash_flow_margin number

Free cash flow margin (FCF Margin).

return_on_invested_capital number

Return on Invested Capital (ROIC).

net_margin number

Net Margin.

return_on_equity number

Return on Equity (ROE).

Growth & Risk

beta number

Beta.

debt_to_equity number

Debt-to-Equity (D/E).

revenue_stability number

Revenue stability.

revenue_growth number

Revenue growth.

eps_growth number

EPS (Earnings Per Share) growth.

Example Response
{
    "task_id": "06181804-0022-0058-0000-c65366875038",
    "status_code": 20000,
    "status_message": "OK",
    "live": true,
    "cost": 0.0002,
    "data": {
        "symbol": "NVDA",
        "tag": "just tag"
    },
    "result": [
        {
            "symbol": "NVDA",
            "dividend_rate": 1,
            "dividend_rate_usd": 1,
            "dividend_yield": 0.48,
            "trailing_annual_dividend_rate": 0.04,
            "trailing_annual_dividend_rate_usd": 0.04,
            "trailing_annual_dividend_yield": 0.01882795,
            "one_year_return": 43.348,
            "three_year_return": 385.829,
            "beta": 2.202,
            "fifty_day_average_change_percent": -0.38336746,
            "two_hundred_day_average_change_percent": 9.422114,
            "free_cash_flow_margin": 0.50366308,
            "return_on_invested_capital": 0.6676865922020258,
            "net_margin": 0.55602534,
            "return_on_equity": 0.58058635,
            "debt_to_equity": 0.05338413,
            "revenue_stability": 0.878539068377033,
            "revenue_growth": 0.5165969048251269,
            "eps_growth": 0.6632099331361276
        }
    ]
}

Notes

  • Percent-like fields are returned as fractions (e.g., 0.02 = 2%). 
  • Some fields may be null depending on asset type and data coverage. It does not indicate an error; it reflects asset-specific applicability.
  • All metric names, field definitions, and calculation details are defined in the Glossary.