Get Financial Metrics Time Series Data

curl --request GET \
  --url https://data-tools.prd.arrays.org/api/v1/stocks/financial-metrics \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://data-tools.prd.arrays.org/api/v1/stocks/financial-metrics', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://data-tools.prd.arrays.org/api/v1/stocks/financial-metrics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://data-tools.prd.arrays.org/api/v1/stocks/financial-metrics"

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

	req.Header.Add("X-API-Key", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://data-tools.prd.arrays.org/api/v1/stocks/financial-metrics")

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

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

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

{
  "data": [
    {
      "metric": "REVENUE_TTM",
      "symbol": "AAPL",
      "values": [
        {
          "fiscal_year": "2024",
          "observed_at": 1672531200,
          "period": "Q4",
          "value": 385000000000.12
        }
      ]
    }
  ],
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "details": [
      {
        "field": "<string>",
        "got": "<string>",
        "reason": "<string>"
      }
    ],
    "docs_url": "<string>",
    "examples": [
      "<string>"
    ],
    "hint": "<string>",
    "message": "The requested resource was not found.",
    "suggestions": [
      "<string>"
    ]
  },
  "metadata": "<unknown>",
  "pagination": "<unknown>",
  "request_id": "<string>",
  "success": true
}

{
  "data": "<unknown>",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "details": [
      {
        "field": "<string>",
        "got": "<string>",
        "reason": "<string>"
      }
    ],
    "docs_url": "<string>",
    "examples": [
      "<string>"
    ],
    "hint": "<string>",
    "message": "The requested resource was not found.",
    "suggestions": [
      "<string>"
    ]
  },
  "metadata": "<unknown>",
  "pagination": "<unknown>",
  "request_id": "<string>",
  "success": true
}

{
  "data": "<unknown>",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "details": [
      {
        "field": "<string>",
        "got": "<string>",
        "reason": "<string>"
      }
    ],
    "docs_url": "<string>",
    "examples": [
      "<string>"
    ],
    "hint": "<string>",
    "message": "The requested resource was not found.",
    "suggestions": [
      "<string>"
    ]
  },
  "metadata": "<unknown>",
  "pagination": "<unknown>",
  "request_id": "<string>",
  "success": true
}

Stock

Get Financial Metrics Time Series Data

OpenAPI JSON Spec Retrieve time series data for 28 different types of financial metrics for stocks

Overview This endpoint provides time series data for 28 financial metrics, including TTM metrics, MRQ ratios, and various growth rates. These metrics are essential for financial analysis, valuation, and investment decision-making.

Key Use Cases

Financial Analysis: Evaluate company profitability, efficiency, and solvency
Investment Screening: Filter stocks based on fundamental metrics
Trend Analysis: Track how financial metrics evolve over time
Comparative Analysis: Compare metrics across different companies

Metric Types

TTM Base Metrics (3 metrics) TTM = Trailing Twelve Months (sum of current quarter + previous 3 quarters)

REVENUE_TTM: Total revenue over the trailing twelve months (pre-calculated sum of 4 quarters)
NET_INCOME_TTM: Net income over the trailing twelve months (pre-calculated sum of 4 quarters)
EPS_TTM: Earnings per share over the trailing twelve months (pre-calculated sum of 4 quarters)

TTM Profitability Ratios (3 metrics)

ROE_TTM: Return on equity over the trailing twelve months (uses MRQ point-in-time equity)
ROA_TTM: Return on assets over the trailing twelve months (uses MRQ point-in-time assets)
ROIC_TTM: Return on invested capital over the trailing twelve months (uses MRQ point-in-time invested capital components)

MRQ Margin Ratios (3 metrics) MRQ = Most Recent Quarter

GROSS_MARGIN_MRQ: Gross profit margin for the most recent quarter
OPERATING_MARGIN_MRQ: Operating profit margin for the most recent quarter
NET_MARGIN_MRQ: Net profit margin for the most recent quarter

MRQ Other Ratios (2 metrics)

FCF_MARGIN_MRQ: Free cash flow margin for the most recent quarter
RD_TO_SALES_TTM: R&D expense as a share of revenue over trailing twelve months

MRQ Balance Sheet Ratios (5 metrics) All values use Most Recent Quarter (MRQ) balance sheet data

DEBT_TO_EQUITY_MRQ: Most recent quarter debt-to-equity ratio
DEBT_TO_ASSETS_MRQ: Most recent quarter debt-to-assets ratio
CURRENT_RATIO_MRQ: Most recent quarter current ratio
QUICK_RATIO_MRQ: Most recent quarter quick ratio (acid-test ratio)
NET_WORKING_CAPITAL_MRQ: Net working capital at the most recent quarter (an absolute value, not a ratio)

Revenue Growth Metrics (4 metrics)

REVENUE_GROWTH_QOQ: Quarter-over-quarter revenue growth rate
REVENUE_GROWTH_YOY_QUARTERLY: Year-over-year quarterly revenue growth rate
REVENUE_GROWTH_YOY_TTM: Year-over-year trailing twelve months revenue growth rate
REVENUE_GROWTH_YOY_ANNUAL: Year-over-year annual revenue growth rate

EPS Growth Metrics (4 metrics)

EPS_GROWTH_QOQ: Quarter-over-quarter earnings per share growth rate
EPS_GROWTH_YOY_QUARTERLY: Year-over-year quarterly earnings per share growth rate
EPS_GROWTH_YOY_TTM: Year-over-year trailing twelve months earnings per share growth rate
EPS_GROWTH_YOY_ANNUAL: Year-over-year annual earnings per share growth rate

FCF Growth Metrics (4 metrics)

FCF_GROWTH_QOQ: Quarter-over-quarter free cash flow growth rate
FCF_GROWTH_YOY_QUARTERLY: Year-over-year quarterly free cash flow growth rate
FCF_GROWTH_YOY_TTM: Year-over-year trailing twelve months free cash flow growth rate
FCF_GROWTH_YOY_ANNUAL: Year-over-year annual free cash flow growth rate

Response Data Structure

Data is grouped by time (timestamp) and sorted in descending order by time. Each time group contains:

time: Observation timestamp (Unix timestamp in seconds, UTC)
items: Array of symbol-value pairs for this time, each containing:
symbol: Stock ticker symbol (e.g., “AAPL”)
value: Metric value (double precision, may be negative or decimal)

Usage Examples

Get AAPL’s TTM revenue data: ?metric=REVENUE_TTM&symbol=AAPL&start_time=1672531200&end_time=1704067200
Get ROE data for all stocks: ?metric=ROE_TTM&start_time=1672531200&end_time=1704067200
Get TSLA’s revenue growth rate: ?metric=REVENUE_GROWTH_YOY_TTM&symbol=TSLA&start_time=1672531200&end_time=1704067200

Important Notes

Required parameters: metric, start_time, end_time
Optional parameter: symbol (if omitted, returns data for all stocks)
All timestamps are Unix timestamps in seconds (UTC)
Metric values are double precision floating-point numbers
Results are grouped by time and sorted in descending order by time (newest first)
TTM metrics: sum of current quarter + previous 3 quarters (pre-calculated)
MRQ metrics: most recent quarterly or period-end values
Ratio metrics: expressed as decimals (e.g., 0.25 means 25% or ratio of 0.25:1)
Growth rates: expressed as decimals (NOT percentages). Example: 0.155 means 15.5% growth; -0.102 means 10.2% decline
ROE/ROA denominators use MRQ point-in-time values (not period averages)
Absolute values: NET_WORKING_CAPITAL_MRQ returns actual dollar amount, not a ratio

GET

stocks

financial-metrics

Get Financial Metrics Time Series Data

curl --request GET \
  --url https://data-tools.prd.arrays.org/api/v1/stocks/financial-metrics \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://data-tools.prd.arrays.org/api/v1/stocks/financial-metrics', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://data-tools.prd.arrays.org/api/v1/stocks/financial-metrics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://data-tools.prd.arrays.org/api/v1/stocks/financial-metrics"

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

	req.Header.Add("X-API-Key", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://data-tools.prd.arrays.org/api/v1/stocks/financial-metrics")

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

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

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

{
  "data": [
    {
      "metric": "REVENUE_TTM",
      "symbol": "AAPL",
      "values": [
        {
          "fiscal_year": "2024",
          "observed_at": 1672531200,
          "period": "Q4",
          "value": 385000000000.12
        }
      ]
    }
  ],
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "details": [
      {
        "field": "<string>",
        "got": "<string>",
        "reason": "<string>"
      }
    ],
    "docs_url": "<string>",
    "examples": [
      "<string>"
    ],
    "hint": "<string>",
    "message": "The requested resource was not found.",
    "suggestions": [
      "<string>"
    ]
  },
  "metadata": "<unknown>",
  "pagination": "<unknown>",
  "request_id": "<string>",
  "success": true
}

{
  "data": "<unknown>",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "details": [
      {
        "field": "<string>",
        "got": "<string>",
        "reason": "<string>"
      }
    ],
    "docs_url": "<string>",
    "examples": [
      "<string>"
    ],
    "hint": "<string>",
    "message": "The requested resource was not found.",
    "suggestions": [
      "<string>"
    ]
  },
  "metadata": "<unknown>",
  "pagination": "<unknown>",
  "request_id": "<string>",
  "success": true
}

{
  "data": "<unknown>",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "details": [
      {
        "field": "<string>",
        "got": "<string>",
        "reason": "<string>"
      }
    ],
    "docs_url": "<string>",
    "examples": [
      "<string>"
    ],
    "hint": "<string>",
    "message": "The requested resource was not found.",
    "suggestions": [
      "<string>"
    ]
  },
  "metadata": "<unknown>",
  "pagination": "<unknown>",
  "request_id": "<string>",
  "success": true
}

Authorizations

X-API-Key

string

header

required

API Key authentication. Example: "your-api-key-here"

Query Parameters

metric

enum<string>

required

Metric type (enum, required)

Available options:

REVENUE_TTM,

NET_INCOME_TTM,

EPS_TTM,

ROE_TTM,

ROA_TTM,

ROIC_TTM,

GROSS_MARGIN_MRQ,

OPERATING_MARGIN_MRQ,

NET_MARGIN_MRQ,

FCF_MARGIN_MRQ,

RD_TO_SALES_TTM,

DEBT_TO_EQUITY_MRQ,

DEBT_TO_ASSETS_MRQ,

CURRENT_RATIO_MRQ,

QUICK_RATIO_MRQ,

NET_WORKING_CAPITAL_MRQ,

REVENUE_GROWTH_QOQ,

REVENUE_GROWTH_YOY_QUARTERLY,

REVENUE_GROWTH_YOY_TTM,

REVENUE_GROWTH_YOY_ANNUAL,

EPS_GROWTH_QOQ,

EPS_GROWTH_YOY_QUARTERLY,

EPS_GROWTH_YOY_TTM,

EPS_GROWTH_YOY_ANNUAL,

FCF_GROWTH_QOQ,

FCF_GROWTH_YOY_QUARTERLY,

FCF_GROWTH_YOY_TTM,

FCF_GROWTH_YOY_ANNUAL

symbol

string

Stock symbol (optional, e.g., AAPL)

start_time

integer<int64>

required

Start time (Unix timestamp in seconds)

end_time

integer<int64>

required

End time (Unix timestamp in seconds)

Response

Successfully retrieved financial metrics data

data

object[]

Show child attributes

error

object

Show child attributes

metadata

any

pagination

any

request_id

string

success

boolean