Warm Metric Cache Status

Poll a background cache-warming job returned by warm_metric_cache.

Tier: paid | Cache: cache-only | 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/job_example_123" \
  -H "Authorization: Bearer $EDGAR_API_KEY"


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

Key Response Fields

Field	Type	Why It Matters
`status`	`"accepted" \| "running" \| "done" \| "partial" \| "failed"`	Transport-level success indicator inside the JSON response.
`items`	`array<object>`	Per-item details for batched, paged, or background work.
`job_id`	`string`	Identifier to pass to the matching status endpoint.
`counts`	`object`	Progress counters for background or batched work.
`created_at`	`string`	Financial fact or concept field; inspect unit, period, and source context before using it.
`updated_at`	`string`	Financial fact or concept field; inspect unit, period, and source context before using it.

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.
This tool is cache-only; if the target filing is not warm, warm it through an allowed paid path before retrying.
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.

Warm Metric Cache, Metric Series, Financials

Generated Reference

Contract

Field	Value
Tool	`warm_metric_cache_status`
Method	`GET`
Path	`/api/warm/{job_id}`
Contract version	`1.0.0`
Schema fingerprint	`sha256:f48e0b9a707e404c640822af06d51f3523f54538fed625a24ee06dc220cb3245`

Parameters

Name	Location	Required	Type	Notes
`job_id`	path	yes	`string`

Response Schema (200)


{
  "properties": {
    "counts": {
      "properties": {
        "done": {
          "default": 0,
          "type": "integer"
        },
        "error": {
          "default": 0,
          "type": "integer"
        },
        "pending": {
          "default": 0,
          "type": "integer"
        },
        "running": {
          "default": 0,
          "type": "integer"
        },
        "skipped_cached": {
          "default": 0,
          "type": "integer"
        }
      },
      "type": "object"
    },
    "created_at": {
      "type": "string"
    },
    "items": {
      "items": {
        "properties": {
          "cached": {
            "type": "boolean"
          },
          "duration_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "error_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "full_year_mode": {
            "type": "boolean"
          },
          "idx": {
            "type": "integer"
          },
          "quarter": {
            "type": "integer"
          },
          "status": {
            "enum": [
              "pending",
              "running",
              "done",
              "error",
              "skipped_cached"
            ],
            "type": "string"
          },
          "ticker": {
            "type": "string"
          },
          "year": {
            "type": "integer"
          }
        },
        "required": [
          "idx",
          "ticker",
          "year",
          "quarter",
          "full_year_mode",
          "status",
          "cached"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "job_id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "accepted",
        "running",
        "done",
        "partial",
        "failed"
      ],
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "job_id",
    "status",
    "created_at",
    "updated_at",
    "counts"
  ],
  "type": "object"
}