Warm Metric Cache

Queue paid-tier background warming for metric periods before follow-up reads.

Tier: paid | Cache: cold-allowed | Playground: authenticated only | Contract: 1.0.0

When To Use It

Use these tools when the model needs normalized financial facts, concept-level series, or statement-shaped outputs grounded in XBRL.

Request Examples


BASE_URL="${EDGAR_API_URL:-https://www.edgarparser.com}"
 
curl -sS "$BASE_URL/api/warm" \
  -X POST \
  -H "Authorization: Bearer $EDGAR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'


import os
import requests
 
base_url = os.getenv("EDGAR_API_URL", "https://www.edgarparser.com")
headers = {"Authorization": f"Bearer {os.environ['EDGAR_API_KEY']}"}
payload = {}
 
response = requests.post(f"{base_url}/api/warm", headers=headers, json=payload, timeout=30)
response.raise_for_status()
data = response.json()

Response Fields To Inspect

status / semantic_status for whether the tool produced a usable fact set.
coverage_status and coverage_warning before treating the value as complete.
source_ref, concept names, units, and period metadata for citation and auditability.

Errors And Coverage

401 or 403: the API key is missing, expired, or not allowed to use this tier.
429: retry after the rate-limit window, and prefer broader batch or series tools over repeated single-period calls.
Cold work can take longer and may queue background fetch or parse work; use status fields or follow-up tools before finalizing.
Paid or LLM-backed paths should be used only when cheaper fact, filing, table, or text tools cannot answer the question.
Treat partial coverage, empty arrays, and warning fields as answer-quality signals even when HTTP status is 200.

Metric Series, Financials, Warm Metric Cache Status

Generated Reference

Contract

Field	Value
Tool	`warm_metric_cache`
Method	`POST`
Path	`/api/warm`
Contract version	`1.0.0`
Schema fingerprint	`sha256:1636aba36d166ecf2901e72078fc8a6182f7174e541d9183561392781e8f8cbd`

Parameters

Name	Location	Required	Type	Notes
none	-	-	-	-

Request Body Schema


{
  "additionalProperties": false,
  "properties": {
    "items": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "full_year_mode": {
            "default": false,
            "type": "boolean"
          },
          "quarter": {
            "maximum": 4.0,
            "minimum": 1.0,
            "type": "integer"
          },
          "ticker": {
            "type": "string"
          },
          "year": {
            "type": "integer"
          }
        },
        "required": [
          "ticker",
          "year",
          "quarter"
        ],
        "type": "object"
      },
      "minItems": 1,
      "type": "array"
    }
  },
  "type": "object"
}

Response Schema (201)


{
  "properties": {
    "items_enqueued": {
      "type": "integer"
    },
    "items_received": {
      "type": "integer"
    },
    "items_skipped_cached": {
      "type": "integer"
    },
    "job_id": {
      "type": "string"
    },
    "poll_url": {
      "type": "string"
    },
    "status": {
      "const": "accepted",
      "type": "string"
    }
  },
  "required": [
    "job_id",
    "status",
    "items_received",
    "items_enqueued",
    "items_skipped_cached",
    "poll_url"
  ],
  "type": "object"
}