Provenio — Art Intelligence

Cost: ~variable. Forward a JSON HTTP request to YOUR own external API endpoint and return the response. Use when: you need to query a third-party art-market source (Artnet/Artprice/your own gallery DB) that we do not host. Auth: pass your API key in MCP request header 'x-byok-auth' — we forward it as Authorization to your endpoint. Allowed hosts: must match an HTTPS URL on the public internet (no internal IPs, localhost, file://, etc). Returns: {status, body, headers, fetched_at, source_url} — body parsed if JSON, raw if not. Logged for your own audit trail; never trained on. We do NOT cache or persist response bodies.

Cost: ~4s. Side-by-side career trajectory comparison for two artists. Returns full trajectory data for each + a structured comparison: pattern overlap score, career stage delta, exhibition/market delta, interpretation, and recommendation. Use when: gallery wants to pitch an emerging artist by showing they mirror a validated comparable's early career. Use when: curator needs narrative evidence that artist A is at the same inflection point artist B was at in year X. Do NOT use when: you need data on one artist — use get_career_trajectory instead. Do NOT use when: you want to discover emerging artists — use find_emerging_artists_by_pattern instead.

Fetch the full Provenio record for an id returned by `search` (person:… or artwork:…). Returns {id, title, text, url, metadata} where text is a readable provenance/market/influence summary. (ChatGPT connector document-fetch tool — wraps get_artist / get_artwork.)

Cost: ~2s. Comparable set. EITHER artwork_id seed → similar works, OR artist_id seed → peer artists. Not for same-artist lot history (use search_auction_history).

Cost: ~3s. Discover emerging artists whose current KG footprint matches a historical career pattern. Patterns: A=institutional_escalation, B=curator_championing, C=movement_anchor, D=late_market_discovery, E=diaspora_rediscovery. Returns ranked candidates with confidence score, exhibition/market data, and signal summary. Use when: gallery wants a shortlist of artists at an early inflection point matching a proven pattern. Use when: curator is building a thematic exhibition and wants artists at the right career stage. Use when: collector wants names not yet on the market radar. Do NOT use when: you already have a specific artist in mind — use get_career_trajectory instead. Do NOT use when: you want to compare two artists — use compare_career_patterns instead. Coverage note: results depend on exhibition data ingested; artists with no exhibition records won't appear.

Cost: ~1s. Find all galleries that represent (currently or formerly) a specific artist. Returns: ordered list of representations (current first, then deceased_estate, then former), with gallery tier/city/country and period. Use when: verifying primary-market representation for valuation or attribution context. Use when: building artist-centric outreach (which galleries control supply). Use when: tracking representation history for a deceased artist's estate.

Cost: ~1s. Composite artist profile — identity + reception + 1-hop influence in/out + education + market aggregates. SINGLE CALL USUALLY SUFFICIENT. Use when: you have an artist ID and need their full picture. Do NOT chain with get_influence_network unless you need depth > 1. Do NOT use for multi-artist comparison — use query_market_summary.

Cost: ~1s. Composite artwork profile — metadata + Panofsky subjects + reception + custody + polity + transactions. SINGLE CALL USUALLY SUFFICIENT. Use when: you have an artwork ID. Do NOT chain with get_provenance_chain unless you need gap-risk flags specifically.

Cost: ~2s. Artist career trajectory analysis: milestones, career stage, pattern detection (A–E), and comparable historical artists who followed the same path. Career stages: PRE_MARKET → REGIONAL → CRITICAL_PHASE → MARKET_ENTRY → ESTABLISHED. Patterns: A=institutional escalation, B=curator championing, C=movement anchor, D=late market discovery, E=diaspora rediscovery. Use for: emerging artist discovery, gallery acquisition decisions, curator narrative building. Do NOT use for purely biographical queries — use get_artist instead.

Cost: ~0.5s–1s. Exhibition history for an artist OR artwork. SINGLE CALL. Returns normalised exhibition records (exhibitions table) when available; falls back to knowledge-graph event nodes (raw_json scan) when the normalised table is empty. Coverage: 94 curated events for 20+ artists as of 2026-04-24. For artists with no data, returns actionable guidance including the exact CLI command to run artsy_exhibitions.py to ingest missing records. Always returns coverage_gaps and suggested_next_tools when data is sparse or absent.

Cost: ~1s. Get the represented-artist roster for a specific gallery. Returns: gallery metadata + ordered list of artists with exclusivity (exclusive/shared/former/deceased_estate), period, notes. Use when: preparing pitch context for a specific gallery (cold email, fair planning). Use when: validating whether artist representation overlap exists between two galleries. Do NOT use when: you only have the artist name — use find_galleries_by_artist instead.

Cost: ~2-3s. N-hop influence BFS. Use ONLY when depth>1 needed — get_artist already has 1-hop.

Cost: ~1s. Formal teacher/student cluster (education_lineage). Use for academic lineage. For conceptual influence: get_influence_network.

Cost: ~0.5s. Concept node + linked artworks. Pass cross_tradition=true for hasFunctionalAnalog concepts (lotus↔rose). SINGLE CALL USUALLY SUFFICIENT. Use when: definitional context or iconography cluster. Do NOT use for artwork filters — use search_artworks.

Cost: ~1s. Custody timeline + gap-risk flags (Nazi, colonial, Russian Rev, Knoedler 1970-2009). Use only for deep due diligence — get_artwork already has basic custody.

Cost: ~1s. Time-ordered reception claims for artist or artwork. Use for valence-shift narrative. Use query_reception_price_correlation if you also need price.

Cost: ~0.5s. Search the Europeana cultural heritage corpus (~50M records from EU museums/archives) for art records. Use when: triangulating Provenio data against European museum holdings, or finding object records with images for a Western European artist. Returns: {total, items: [{title, creator, dataProvider, year, image_url, edm_url}]} Source: api.europeana.eu (public-domain Europe gateway, demo key embedded; users can supply own key via byok_external_query for high-volume).

Cost: ~0.3s. Search the Metropolitan Museum of Art collection (free public API · ~480K objects) and optionally dereference an objectID. Use when: you need a museum-confirmed match for an artist or work, or want to triangulate Provenio data against Met holdings. Returns either {total, objectIDs[]} for a search OR a full object record if object_id supplied. Source: https://collectionapi.metmuseum.org/public/collection/v1 · zero PII, public domain images flagged.

Cost: ~3-8s. Run a SPARQL query against Wikidata (public, no auth) for art-related entities. Use when: you need cross-museum location data for an artist's works, or biographical data not in Provenio. Pattern: pass a SPARQL query string. Example below to get all Klimt artworks with current location. Returns: {total, bindings: [...]} — raw SPARQL JSON results format. Source: https://query.wikidata.org/sparql · 12-second SPARQL query timeout enforced.

Cost: ~2s. Per-artist market aggregates × reception × polity. Use for cross-artist comparison. Single artist deep profile: get_artist. Individual lots: search_auction_history.

Cost: ~2s. Polity-origin artworks now dispersed. Use for restitution/cultural-heritage analysis. For simple list: search_artworks.

Cost: ~2s. Reception × price timeline for one artist. Combines get_reception_arc + price trend in one call.

Search the Provenio art-provenance knowledge graph (artists + artworks) by free text. Returns a ranked list of {id, title, url}. Pass an id to `fetch` for the full record. Use this as the entry point for any name/title lookup. (ChatGPT connector entry tool — wraps search_artists + search_artworks.)

Cost: ~0.4s. Shortlist person nodes by name/nationality/era. Returns [{id, display_name, birth_year, death_year, nationality, era}]. Use when: you have a name but no person ID. Try a partial name if exact match fails (e.g. 'Basquiat' not 'Jean-Michel Basquiat'). Do NOT use if: you already know the ID — call get_artist directly (one call). Returns person IDs in 'person:slug' format — pass these directly as the 'artist' parameter in search_artworks. STOP after this unless you need a specific artist's full profile.

Cost: ~0.5s. Shortlist artworks by title/artist/medium/date, or risk-filter (provenance_risk, attribution_status). Returns summary rows. Use when: you need a list, not one work's detail. Do NOT use if: you know the artwork ID — call get_artwork (one call contains iconography + custody + polity + transactions). Do NOT chain multiple search_artworks calls for the same work — use get_artwork after you have the ID. Do NOT put artist names in the query field alone — use the artist filter with the person ID slug (e.g. 'person:jean-michel-basquiat'). If title is ambiguous, combine query + artist filter. Title match is substring (ILIKE %query%). For best results, use the artist filter rather than embedding artist name in query. Note: when provenance_risk filter is used, returns coverage_gaps: ['no_custody_history'] when the matching custody record pool is smaller than expected — interpret this as a data-density limitation, not a clean result. STOP after this unless you need deep detail on ONE artwork.

Cost: ~0.7s. Auction transaction rows with optional percentile_summary=true to also return P25/50/75/90 + realized-vs-estimate in ONE call. Use when: need lot-level prices OR percentile stats. Do NOT use if: you only need per-artist aggregates — use query_market_summary. SINGLE-CALL FRIENDLY — combine filters + percentile_summary for appraisal work.

Cost: ~1s. Search galleries by name, tier, country, or city. Tiers: mega (Gagosian/Zwirner level), major (international program), boutique (focused), emerging (newer). Use when: identifying which galleries operate in a specific market or tier band. Use when: building a B2B target list (galleries by region/tier). Do NOT use when: you want to know which gallery represents a specific artist — use find_galleries_by_artist instead.