Find a fund (resolve a name/code to an Instrument Key)find_fund
You have a fund name, ticker, Fundserv/CUSIP/ISIN code, or company — but not an Instrument Key.
- Call webdata_fund_search with query=<the text or code> and query_type='auto' (or set it explicitly, e.g. 'fundserv' for a dealer code, 'company' + scope='company' to list a company's funds).
- Scan the results; choose the row whose company / seriesname / currency matches the user's intent and take its instrumentkey.
- If several plausible matches remain (multiple series or currencies), ask the user to disambiguate rather than guessing.
webdata_fund_searchwebdata_instrument_getidentifiers
- A fund typically has several series (F, B, USD, ...) each with its own Instrument Key — confirm the right one before proceeding.
- webdata_fund_search is the only name -> key path; instrument/getidentifiers resolves a known code -> key.
- Use limit/offset to page large company result sets.
ReturnsThe chosen instrumentkey (and why), or a short disambiguation list for the user to pick from.
Overview of a single fundfund_overview
The user wants a rounded picture of one fund.
- Resolve the instrumentkey (see find_fund).
- Call webdata_fund_getprofile(instrumentkey, language) — one call returning general, manager, fees, performance and risk.
- Drill into specific tools only if more depth is needed: gettopholding, getallocations, getmonthlyperformance/getyearlyperformance.
webdata_fund_searchwebdata_fund_getprofilewebdata_fund_gettopholdingwebdata_fund_getallocations
- Prefer getprofile over five separate calls.
- Filter to a single language.
- State the as-of / reporting date so the user knows how current the data is.
ReturnsIdentity, objective, key performance, fees and risk for the fund, with the as-of date.
Compare two or more fundscompare_funds
The user wants funds side by side — performance, fees, holdings, or risk.
- Resolve each fund to an instrumentkey (find_fund).
- For each key call webdata_fund_getprofile for the rounded view.
- For deeper comparison, call the SAME tool for each fund: getperformancesummary, getallocations, or the fee tools.
- Align: use one language for all funds; compare like series/currency; note that each fund reports on its own date.
webdata_fund_searchwebdata_fund_getprofilewebdata_fund_getperformancesummarywebdata_fund_getallocations
- Funds report on staggered dates — do not assume a common as-of date.
- Compare comparable series/currency (an F-series and an A-series differ on fees).
- Keep one language throughout to avoid duplicate/mismatched rows.
ReturnsA side-by-side of identity / returns / fees / risk, plus caveats on any date or coverage mismatch.
Fund performance and returnsperformance
How a fund has performed — headline returns, over time, or vs peers.
- Resolve the instrumentkey.
- Headline: webdata_fund_getperformancesummary (returns across standard periods; one row per fund).
- Over time: webdata_fund_getmonthlyperformance / webdata_fund_getyearlyperformance.
- Peer context: webdata_fund_getperformancesummaryranking / webdata_fund_getyearlyperformanceranking.
- Risk-adjusted: webdata_fund_getadvancedperformance / webdata_fund_getyearlyperformancerisk.
webdata_fund_getperformancesummarywebdata_fund_getmonthlyperformancewebdata_fund_getyearlyperformancewebdata_fund_getperformancesummaryrankingwebdata_fund_getadvancedperformance
- Time-series rows are keyed by Instrument Key + date/period.
- Monthly/yearly performance is revised over time; the update date and the month-end date can differ.
- Rankings are within the fund's CIFSC peer group.
ReturnsReturns over the requested horizon with peer and/or risk-adjusted context, and the as-of period.
Holdings and market exposureholdings_exposure
What a fund holds and how it is allocated across assets/sectors/regions.
- Resolve the instrumentkey.
- Top holdings: webdata_fund_gettopholding (top 10 by market %). Full list: webdata_fund_getfullholding.
- Exposure: webdata_fund_getallocations with allocationstype Asset | Sector | Geo.
- Style detail: webdata_fund_getequitystyleallocation / webdata_fund_getfixedincomestyleallocation.
webdata_fund_gettopholdingwebdata_fund_getfullholdingwebdata_fund_getallocationswebdata_fund_getequitystyleallocation
- Holdings and allocations come in EN and FR rows — filter to one language before aggregating or you will double-count.
- Top holdings use a Holding Number ordinal; some funds give a rank without a market value.
ReturnsTop holdings and asset/sector/geo exposure for one language, as of the reporting date.
Fees and cost of ownershipfees
The loads, MER/expenses, trailers, and other fees for a fund.
- Resolve the instrumentkey (getprofile's 'fees' section gives a quick summary first).
- Loads/sales charges: webdata_fund_getload. Other fees: webdata_fund_getotherfees.
- Expenses/MER: webdata_fund_getexpense. Trailers: webdata_fund_gettrailerschedule.
webdata_fund_getloadwebdata_fund_getotherfeeswebdata_fund_getexpensewebdata_fund_gettrailerschedule
- Fees are keyed by Fundserv code and by fee type — one series can have several rows.
- Expenses are a time series (by date).
ReturnsLoads, MER/expenses, trailers and other fees for the series, noting the Fundserv code.
Risk profilerisk
How risky a fund/instrument is.
- Resolve the instrumentkey.
- Risk ratings: webdata_instrument_getrisk (regulatory + calculated, by risk source).
- Risk-adjusted performance: webdata_fund_getadvancedperformance, webdata_fund_getyearlyperformancerisk.
- Investor context: webdata_fund_getsuitability.
webdata_instrument_getriskwebdata_fund_getadvancedperformancewebdata_fund_getyearlyperformanceriskwebdata_fund_getsuitability
- There can be multiple risk sources per instrument — say which source you are reporting.
- instrument/getrisk is unique by Instrument Key + Risk Source + Language.
ReturnsRisk rating(s) with their source, plus risk-adjusted metrics.
Income, distributions and pricing historyincome_distributions
Distributions, yield, or NAVPS/price history for a fund.
- Resolve the instrumentkey.
- Distributions: webdata_fund_getdistribution (by date). Daily NAVPS/yield: webdata_fund_getdailynavps. Month-end price: webdata_fund_getmonthlyprice.
webdata_fund_getdistributionwebdata_fund_getdailynavpswebdata_fund_getmonthlyprice
- All are keyed by Instrument Key + Date; distributions are sparsely populated.
- To relate a distribution to price, join on Instrument Key + Date.
ReturnsDistribution history and/or NAVPS over the requested dates.
Suitability, objective and availabilitysuitability
Who a fund is for, its objective, minimums, and how it is sold.
- Resolve the instrumentkey.
- Suitability: webdata_fund_getsuitability. Objective: webdata_fund_getstandardizedobjective.
- Minimums: webdata_fund_getminimuminvestment. Sales/availability: webdata_fund_getsalesinformation.
webdata_fund_getsuitabilitywebdata_fund_getstandardizedobjectivewebdata_fund_getminimuminvestmentwebdata_fund_getsalesinformation
- These are per language.
- Sales information reflects current availability/status.
ReturnsIntended investor, objective, minimum investment and availability.
Compare a fund to its benchmarkbenchmark_compare
The user wants a fund measured against its benchmark index.
- Resolve the fund's instrumentkey.
- webdata_fund_getassociatedbenchmark(instrumentkey) -> MANY rows (one per BenchmarkType). Select the row you want (usually BenchmarkType='Associated Index Category') and take its BenchmarkInstrumentKey.
- Benchmark performance: webdata_benchmark_getperformancesummary / getmonthlyperformance / getyearlyperformance on the benchmark key.
- Fund side: the matching fund performance tools; align periods and frequency.
webdata_fund_getassociatedbenchmarkwebdata_benchmark_getperformancesummarywebdata_benchmark_getmonthlyperformancewebdata_fund_getperformancesummary
- getassociatedbenchmark returns MANY rows per fund - one per BenchmarkType (median, category averages by channel, and the associated index). Do not treat this as duplicates; pick the BenchmarkType you want.
- For a real fund-vs-index comparison choose BenchmarkType 'Associated Index Category'; the 'Avg/Median Category' types are peer-group aggregates, not an index.
- The benchmark has its OWN Instrument Key (BenchmarkInstrumentKey from getassociatedbenchmark) - do not reuse the fund's key.
- Align periods/frequency (monthly vs yearly) and language before comparing.
ReturnsFund vs benchmark returns over aligned periods.
Keep your own database current (DbSync)bulk_sync
You maintain your OWN datastore of Fundata content — not for answering a single user question.
- Call the dbsync_* tool for each table you track with a fromdate = your last sync date.
- Each call starts a job and returns an execution_id; call dbsync_get_results(execution_id) until status='ready' with a download_url.
- Fetch the download_url directly (not through this server) and load/upsert it into your database.
- Store MonthEndDate/Date as the time key for the time-series tables.
dbsync_fund_getgeneraldbsync_fund_getdailynavpsdbsync_get_results
- DbSync is not a historical archive — only explicitly time-series tables carry history; others are current-state at extract time.
- Fetch the download_url directly; routing large files through the server wastes the NAT.
- For answering a single user question, use the webdata tools instead.
ReturnsA pointer to the delta file(s) to load and the keys to upsert on.
Screen / rank funds (top or bottom N by a metric)screen_funds
The question is comparative or ranked across many funds - "who has the best 1-year return", "lowest-MER F-class funds", "highest 3-year Sharpe in Canadian Equity" - rather than about one known fund.
- Call webdata_fund_screening. Put narrowing criteria in filters as {field, op, value} conditions (AND-combined), e.g. {"field":"cifsctype","op":"eq","value":"Canadian Equity"} and {"field":"shareclass","op":"eq","value":"F"}.
- Set sort_by to the ranking metric and sort_dir: desc for best/highest (top returns, top Sharpe), asc for worst/lowest (lowest MER, lowest volatility).
- Set limit to how many you need (max 50); add the metrics you want to show in select (rows always include instrumentkey, language, legalname).
- Read total_matched to see the full count; page with offset (25, 50, ...) if you need more than one page.
- Take instrumentkey from any row to drill in with webdata_fund_getprofile or the specific fund/* tools.
webdata_fund_screeningwebdata_fund_getprofile
- Screening is series-level: a fund appears once per series (share class) that matches - filter on shareclass to compare like-for-like.
- Use screening instead of calling webdata_fund_search + many getprofile/getperformancesummary calls when the question is a ranking or filter - one call, far fewer round-trips.
- op supports eq, ne, in, contains, gt, gte, lt, lte; use in with a list of values, contains for substring name/objective matches.
- limit is capped at 50; metrics reflect each fund latest available reporting date, so ranked figures are not all as-of the same day.
ReturnsA ranked, projected list of funds (with instrumentkey) answering the comparative question, plus total_matched for paging.
Build an ingestion platform / integration against Fundata (developer)build_integration
A developer wants to design or code a solution that ingests Fundata data (a database sync, a display layer, or an app) and is using you as a build-time reference to the API — not to answer a one-off data question.
- Decide the family per use: WebData = latest values for direct display/point queries (returned inline); DbSync = delta 'changed since fromdate' extracts to build/maintain your OWN datastore. Most ingestion pipelines are DbSync.
- Model the schema from the API's own description: call describe_dataset(<tool_name>) for each dataset you'll store to get fields (name/type/length), unique_by (the natural/primary key), grain, and cardinality (how many rows per fund).
- Model the relationships with data_model(): every dataset joins fund/getgeneral on Instrument Key (the hub); each dataset's grain adds composite keys (Language, Date/MonthEndDate/Year, *Type, Rank/Holding Number). Use Instrument Key as the foreign key throughout; resolve external codes (Fundserv/CUSIP/ISIN/ticker) to an Instrument Key via instrument/getidentifiers.
- Design the DbSync loop (see how_to('bulk_sync')): call each dbsync_* table with fromdate = your last successful sync; you get an execution_id; poll dbsync_get_results until a download_url is returned; your PLATFORM (not an agent sandbox) fetches that URL and upserts on the dataset's unique_by; persist Date/MonthEndDate as the time key on time-series tables.
- Handle operational realities: respect per-credential rate limits (DbSync has its own stricter budget); expect large extracts (some tables are thousands of rows) so stream/batch the file rather than loading it whole; treat an empty result as normal (see each dataset's cardinality — optional datasets can be 0..1); DbSync is a delta feed, not a historical archive (only explicitly time-series tables carry history).
- For a live/display layer instead of a stored DB, skip DbSync: call the WebData twin of each dataset by Instrument Key and render the returned values directly.
describe_datasetdata_modelusage_guidehow_tolist_endpointswebdata_instrument_getidentifiersdbsync_get_results
- DbSync returns a download_url that the CLIENT fetches directly (kept off this server) — a sandboxed agent usually can't reach result.fundataapiuat.com, but a real ingestion platform can. Use DbSync's schemas/patterns here as a spec to generate code, not to fetch files from inside an agent.
- unique_by is the upsert key — get it from describe_dataset, don't guess; several datasets are keyed by Instrument Key + a composite (Language, a date, a *Type, or a rank).
- Filter to one Language when storing per-language tables or you will double rows.
- Metric values (returns/MER/risk) are latest-available with an implicit as-of (month-end / latest published); if you need explicit reporting dates, they live on the detail tables (getperformancesummary/getprofile), not on screening.
ReturnsA blueprint for the integration: which datasets/tables to store, their keys (unique_by) and joins (Instrument Key hub), the DbSync sync loop, and the operational constraints (rate limits, large extracts, entitlements, empties).