DocsPortfolio analysis

SEC fundamental scores

Portfolio analysis

Send tickers and weights, and get what the portfolio is really exposed to: a value-weighted z-score and percentile for each of 10 SEC fundamental factors, the holdings that drive each one, and coverage. No prices, no key needed to start.

What you send

  • positions: a ticker per holding with a weight on every position, or a market_value on every one. Weights need not sum to 100.
  • cash: optional, in the same unit as market values. Shown in coverage, never scored.
  • as_of: optional score date. The default is the latest filings. Other dates are a paid feature (as_of_history).

Creo does not price shares, so a position with only a share count gets 422 QUANTITY_NEEDS_VALUE. Use your statement's market value instead.

curl -s -X POST https://itscreo.com/v1/portfolio/analyze \
  -H 'content-type: application/json' \
  -d '{"positions": [{"ticker": "AAPL", "weight": 40},
                     {"ticker": "MSFT", "weight": 35},
                     {"ticker": "JPM", "weight": 25}]}'

What comes back

An excerpt of a real response for that portfolio, as of 2026-11-19:

{
  "as_of": "2026-11-19",
  "methodology_version": "creo-sec-fundamental-scores:1.0.0",
  "headline": "Your book tilts toward large-float, highly profitable companies.",
  "exposures": [
    {
      "factor_id": "quality",
      "exposure": 0.547,
      "percentile": 69.2,
      "coverage": 1.0,
      "tilt": "positive",
      "sentence": "Moderate positive tilt: profitable, cash-backed earnings, modest leverage and steady results."
    },
    {
      "factor_id": "profitability",
      "exposure": 1.269,
      "percentile": 78.2,
      "coverage": 1.0,
      "tilt": "positive",
      "sentence": "Strong positive tilt: earns more gross profit, net income and operating cash per dollar of assets."
    },
    …
  ],
  "holdings": [
    {
      "ticker": "AAPL",
      "company": "Apple Inc.",
      "weight": 0.4,
      "status": "scored",
      "factors": {
        "profitability": {
          "z": 2.247,
          "percentile": 98.9,
          "raw": 0.3461,
          "label": "very high profitability",
          "contribution": 0.8988
        },
        …
      }
    },
    …
  ],
  "coverage": {
    "holdings": 3,
    "scored": 3,
    "partial": 0,
    "unscored": 0,
    "scored_weight": 1.0,
    "cash_weight": 0.0,
    "unscored_by_reason": {}
  }
}
  • exposures[]: the portfolio's weighted z-score per factor, its percentile against US-listed companies, how much of the portfolio is covered, and a plain sentence.
  • holdings[]: each holding's z, percentile, raw value and contribution (weight times z), so you can see which positions drive a tilt.
  • coverage: scored, partial and unscored holdings, with a reason for each unscored one. Unscored holdings are left out of every mean, never counted as zero.
  • as_of and methodology_version, so any answer can be reproduced.

Limits

Without a key: up to 50 tickers per call and 1,000 calls a day per IP address, then 429 RATE_LIMITED with Retry-After. With a key, each call costs one credit and takes up to your plan's holdings limit. See Credits and limits.

Endpoints

POST/v1/portfolio/analyze

Portfolio factor exposures from your holdings' values Key optional

Send tickers with market values (or weights) from your own statement. Returns value-weighted factor z-scores, each holding's contribution, coverage with reasons, and a plain-English sentence per factor. Creo does not price shares: a position with only quantity gets 422 QUANTITY_NEEDS_VALUE. Unscored holdings are left out of each mean, never counted as zero. Keyless: up to 50 positions per call and 1000 calls a day per IP (429 RATE_LIMITED beyond). With an x-api-key each call costs one credit.

Request body

positionsarray of AnalyzePositionrequired
Child fields
tickerstringrequired
market_valuenumbernullable

Signed market value in USD (negative for shorts), from your own statement. Send this or weight.

weightnumbernullable

Signed portfolio weight in any unit (0.25, or 25). Weights are renormalized, so they need not sum to 1.

quantitynumbernullable

Share count, accepted for convenience alongside market_value or weight and otherwise ignored. Creo does not price shares, so quantity alone is rejected with QUANTITY_NEEDS_VALUE.

cashnumber

Cash in the same unit; shown, never scored.

Default 0

as_ofdatenullable

Score date. Default: latest.

Example

curl -X POST https://itscreo.com/v1/portfolio/analyze \
  -H "content-type: application/json" \
  -d '{"positions":[{"ticker":"AAPL","market_value":18250},{"ticker":"MSFT","market_value":12400},{"ticker":"VTI","market_value":9000}],"cash":1500}'

Responses

  • 200Successful Response AnalyzeResponse
  • 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged. Error
  • 400KEY_IN_QUERY: send the key in a header, not the URL Error
  • 401AUTHENTICATION_REQUIRED: missing or invalid key Error
  • 429RATE_LIMITED: daily credits used up Error
Response fields
as_ofdaterequired
methodology_versionstringrequired
universeUniverserequired
Child fields
namestringrequired
sizeintegerrequired
scoredintegerrequired
descriptionstringrequired
quality_flagsarray of stringrequired
headlinestringrequired
factorsarray of FactorDefinitionrequired
Child fields
idstringrequired
labelstringrequired
short_labelstringrequired
high_meansstringrequired
low_meansstringrequired
descriptionstringrequired
raw_labelstringnullable
unitstringnullable
exposuresarray of PortfolioExposurerequired
Child fields
factor_idstringrequired
labelstringrequired
short_labelstringrequired
exposurenumberrequired

Value-weighted mean z-score of covered holdings, on the -3..+3 scale.

percentilenumberrequired

Value-weighted mean of the holdings' cross-sectional percentiles (0-100).

coveragenumberrequired

Share of gross holdings value scored on this factor.

covered_holdingsintegerrequired
tiltenumrequired

One of positive, negative, neutral, unavailable

sentencestringrequired
high_meansstringrequired
low_meansstringrequired
holdingsarray of HoldingResultrequired
Child fields
tickerstringrequired
companystringrequired
weightnumberrequired

Share of total value including cash.

statusenumrequired

One of scored, partial, unscored

reasonstringrequired
factorsmaprequired
coverageCoverageSummaryrequired
Child fields
holdingsintegerrequired
scoredintegerrequired
partialintegerrequired
unscoredintegerrequired
scored_weightnumberrequired

Share of gross holdings value with any score.

cash_weightnumberrequired
unscored_by_reasonmaprequired
creditsmapnullable

Your key's plan and usage; null for keyless calls.

POST/v1/portfolio/scores

SEC fundamental factor z-scores for a list of tickers Key optional

Send tickers only; no quantities or values. Each factor is a cross-sectional z-score (-3..+3) against US-listed SEC filers, built from 10-K and 10-Q filings alone. Unscored tickers carry a reason code. Keyless: up to 50 tickers per call and 1000 calls a day per IP (429 RATE_LIMITED beyond). With an x-api-key each call costs one credit.

Request body

tickersarray of stringrequired
as_ofdatenullable

Example

curl -X POST https://itscreo.com/v1/portfolio/scores \
  -H "content-type: application/json" \
  -d '{}'

Responses

  • 200Successful Response creo__portfolio__scores__ScoreBatch
  • 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged. Error
  • 400KEY_IN_QUERY: send the key in a header, not the URL Error
  • 401AUTHENTICATION_REQUIRED: missing or invalid key Error
  • 429RATE_LIMITED: daily credits used up Error
Response fields
as_ofdaterequired
computed_atdatetimenullable
methodology_versionstringrequired
universeUniverserequired
Child fields
namestringrequired
sizeintegerrequired
scoredintegerrequired
descriptionstringrequired
quality_flagsarray of string
factorsarray of FactorDefinition
Child fields
idstringrequired
labelstringrequired
short_labelstringrequired
high_meansstringrequired
low_meansstringrequired
descriptionstringrequired
raw_labelstringnullable
unitstringnullable
scoresmap
unknown_tickersarray of string
creditsmapnullable