FindData — Data Intelligence Skill

Query global data with a single API call. Supports natural language in English and Chinese.

Simple queries (stock price, GDP, exchange rate) use a fast path — Voyage AI selects the tool and rules extract parameters, no LLM needed (~1s). Complex queries (comparisons, derived metrics like profit margin) use LLM planning to generate a multi-step execution plan (~3-5s).

Endpoint: https://finddata.ai/api/query

Method: POST

Auth: X-API-Key

Content-Type: application/json

Body: {"query": "your natural language question"}

Setup

1. Get your API key at https://finddata.ai (free tier available)
2. Set your environment variable:

export FINDDATA_API_KEY="odh_your_key_here"

If the user provides their key in the message (starts with odh_), extract it and use it directly.

Usage

curl -s -X POST https://finddata.ai/api/query \
  -H "X-API-Key: $FINDDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Apple stock price"}'

More examples

# US economic data
curl -s -X POST https://finddata.ai/api/query \
  -H "X-API-Key: $FINDDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "US inflation rate"}'

# Chinese market data
curl -s -X POST https://finddata.ai/api/query \
  -H "X-API-Key: $FINDDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "贵州茅台股价"}'

# Derived metrics (triggers LLM calculation)
curl -s -X POST https://finddata.ai/api/query \
  -H "X-API-Key: $FINDDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Apple profit margin"}'

# SEC filings
curl -s -X POST https://finddata.ai/api/query \
  -H "X-API-Key: $FINDDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Tesla 10-K annual report"}'

# Global indicators
curl -s -X POST https://finddata.ai/api/query \
  -H "X-API-Key: $FINDDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "India GDP growth"}'

# International trade
curl -s -X POST https://finddata.ai/api/query \
  -H "X-API-Key: $FINDDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "China exports to USA 2023"}'

Sources

Tool selection is automatic — Voyage AI matches your query to the best tool.

Response Format (v5.1)

The response includes: query result, execution details, data quality issues (if any), and usage info.

Always check success first. Then read data.records for the actual data.

Response Structure

{
  "query": "...",
  "success": true,
  "data": {
    "records": { ... },
    "sources": [ { "tool": "...", "source": "...", "dataType": "...", "latencyMs": 123 } ]
  },
  "derived_metrics": { ... },
  "execution": {
    "planMethod": "fast_path | llm | fallback",
    "plan": { "steps": 1, "requiresCalculation": false },
    "toolsUsed": [ { "tool": "...", "params": { ... }, "success": true, "latencyMs": 123 } ],
    "latency_ms": 456
  },
  "issues": [ { "type": "missing | partial | stale | error", "description": "..." } ],
  "usage": { "plan": "free", "latency_ms": 456, "monthly_limit": 100, "cooldown_seconds": 10 }
}

Key Fields

Example 1: Simple stock price (fast path)

Query: "Apple stock price"

{
  "query": "Apple stock price",
  "success": true,
  "data": {
    "records": {
      "ticker": "AAPL",
      "name": "Apple Inc.",
      "price": 173.50,
      "currency": "USD",
      "change": -2.15,
      "changePercent": -1.22,
      "volume": 54321000,
      "marketCap": 2700000000000,
      "pe": 28.5,
      "fiftyTwoWeekHigh": 199.62,
      "fiftyTwoWeekLow": 124.17
    },
    "sources": [
      { "tool": "get_stock_price", "source": "yahoo_finance", "dataType": "quote", "latencyMs": 450 }
    ]
  },
  "execution": {
    "planMethod": "fast_path",
    "plan": { "steps": 1, "requiresCalculation": false },
    "toolsUsed": [
      { "tool": "get_stock_price", "params": { "ticker": "AAPL" }, "purpose": "Fast-path: direct match", "success": true, "source": "yahoo_finance", "latencyMs": 450 }
    ],
    "latency_ms": 890
  },
  "usage": { "plan": "free", "latency_ms": 890, "monthly_limit": 100, "cooldown_seconds": 10 }
}

How to extract the price: response.data.records.price → 173.50

Example 2: Chinese A-Share (fast path)

Query: "贵州茅台股价"

{
  "query": "贵州茅台股价",
  "success": true,
  "data": {
    "records": {
      "type": "a_share_quote",
      "provider": "sina",
      "records": [
        {
          "code": "600519",
          "market": "SH",
          "name": "贵州茅台",
          "price": 1392.00,
          "open": 1395.00,
          "high": 1403.95,
          "low": 1391.01,
          "volume": 2758646
        }
      ]
    },
    "sources": [
      { "tool": "get_a_share_quote", "source": "china_market", "dataType": "a_share_quote", "latencyMs": 320 }
    ]
  },
  "execution": {
    "planMethod": "fast_path",
    "plan": { "steps": 1, "requiresCalculation": false },
    "toolsUsed": [
      { "tool": "get_a_share_quote", "params": { "stock": "贵州茅台" }, "purpose": "Fast-path: direct match", "success": true, "source": "china_market", "latencyMs": 320 }
    ],
    "latency_ms": 680
  },
  "usage": { "plan": "free", "latency_ms": 680, "monthly_limit": 100, "cooldown_seconds": 10 }
}

How to extract the price: response.data.records.records[0].price → 1392.00

Example 3: US economic data (fast path)

Query: "US unemployment rate"

{
  "query": "US unemployment rate",
  "success": true,
  "data": {
    "records": {
      "series_id": "UNRATE",
      "title": "Unemployment Rate",
      "frequency": "Monthly",
      "units": "Percent",
      "observations": [
        { "date": "2024-01-01", "value": "3.7" },
        { "date": "2024-02-01", "value": "3.9" }
      ]
    },
    "sources": [
      { "tool": "get_fred_series", "source": "fred", "dataType": "time_series", "latencyMs": 280 }
    ]
  },
  "execution": {
    "planMethod": "fast_path",
    "plan": { "steps": 1, "requiresCalculation": false },
    "toolsUsed": [
      { "tool": "get_fred_series", "params": { "series_id": "UNRATE" }, "success": true, "source": "fred", "latencyMs": 280 }
    ],
    "latency_ms": 620
  },
  "usage": { "plan": "free", "latency_ms": 620, "monthly_limit": 100, "cooldown_seconds": 10 }
}

How to extract the value: response.data.records.observations[0].value → "3.7"

Example 4: Derived metrics (LLM planning + calculation)

Query: "Apple profit margin"

{
  "query": "Apple profit margin",
  "success": true,
  "data": {
    "records": {
      "type": "financials",
      "company": "APPLE INC",
      "cik": "0000320193",
      "metrics": {
        "Revenues": { "2024-Q3": 85777000000, "2024-Q2": 90753000000 },
        "NetIncomeLoss": { "2024-Q3": 21448000000, "2024-Q2": 23636000000 }
      }
    },
    "sources": [
      { "tool": "get_company_financials", "source": "sec_edgar", "dataType": "financials", "latencyMs": 1200 }
    ]
  },
  "derived_metrics": {
    "profit_margin": {
      "2024-Q3": "25.0%",
      "2024-Q2": "26.0%"
    },
    "calculation": "Net Income / Revenue"
  },
  "execution": {
    "planMethod": "llm",
    "plan": { "steps": 1, "requiresCalculation": true, "calculation": "profit_margin = NetIncomeLoss / Revenues" },
    "toolsUsed": [
      { "tool": "get_company_financials", "params": { "ticker": "AAPL" }, "success": true, "source": "sec_edgar", "latencyMs": 1200 }
    ],
    "latency_ms": 4500
  },
  "usage": { "plan": "free", "latency_ms": 4500, "monthly_limit": 100, "cooldown_seconds": 10 }
}

How to extract derived metrics: response.derived_metrics.profit_margin → { "2024-Q3": "25.0%", ... }

Example 5: Data quality issues

When data cannot be fully retrieved, the issues array explains what happened:

{
  "success": false,
  "issues": [
    {
      "type": "error",
      "description": "Failed to fetch data from get_stock_price: Ticker 'INVALID' not found",
      "tool": "get_stock_price"
    }
  ]
}

Issue types:

• "missing" — No data returned at all
• "partial" — Some data sources failed, partial results available
• "stale" — Data may be outdated (market closed, delayed feed)
• "error" — Tool execution failed with an error

Data Extraction Quick Reference

Parameters

Error Handling

When success is false, check the issues array for details. The error field may also be present at the top level.

{
  "success": false,
  "data": { "records": null, "sources": [] },
  "issues": [
    { "type": "error", "description": "Failed to fetch data: API timeout" }
  ],
  "error": "All data sources failed"
}

HTTP Status Codes