> ## Documentation Index > Fetch the complete documentation index at: https://docs.syrto.ai/llms.txt > Use this file to discover all available pages before exploring further. # Mercato base > Prezzo: 150 crediti, +50 con una ripartizione (area macro o classe dimensionale; una volta per chiamata, quanti che siano i gruppi). 404, mai addebitato, quando nessuna azienda dell'insieme ha depositato per l'anno. Di sola lettura e idempotente: si usa POST solo perché la richiesta ha un corpo. Il metodo HTTP QUERY è il verbo preferito per questa operazione e verrà accettato sullo stesso percorso quando il supporto dei client sarà diffuso. ## OpenAPI ````yaml api-reference/openapi.standard.it.json POST /market/base openapi: 3.1.0 info: title: Syrto API - endpoint standard version: 1.7.0 description: >- Dati finanziari, societari e di mercato sulle aziende italiane. Ogni chiamata risponde `200 { data, meta }`; `meta.usage.quantity` è quanto ha consumato la chiamata, in crediti, e `meta.warnings` elenca eventuali avvertenze non bloccanti (vuoto quando non ce ne sono). Ogni campo è sempre presente e i valori sconosciuti sono null. Le percentuali sono frazioni (0,15 = 15%). **Autenticazione.** Ogni chiamata richiede una chiave API, inviata come `Authorization: Bearer sk_...` su HTTPS - mai in un URL. Le chiavi sono legate alla tua organizzazione: gli admin le creano e le revocano nella dashboard Syrto (https://dashboard.syrto.ai/api-keys). Una chiave mancante o non riconosciuta è un 401 (`missing_api_key`, `invalid_api_key`); un 503 `auth_unavailable` significa che in questo momento non è stato possibile verificare la chiave, quindi riprova con backoff invece di ruotarla. **Base di addebito.** negativities, rna e structure addebitano una volta per persona giuridica: il record individuale e quello consolidato della stessa azienda contano una volta. Ogni altro endpoint addebita per record (o per chiamata), quindi individuale e consolidato contano separatamente. Un codice fiscale si risolve sempre in un solo record (`statementBasis`, individuale per impostazione predefinita): un'azienda viene addebitata due volte solo se vengono passati entrambi i suoi companyId. Una chiamata di mercato ha un prezzo per chiamata, qualunque sia la dimensione dell'insieme: omettere `filters` e `seedId`, o inviare `filters: {}`, significa tutta l'Italia, allo stesso prezzo. Le voci notFound non vengono mai addebitate, e nemmeno alcun errore. servers: - url: https://api.syrto.ai security: [] tags: - name: Company data description: Identità, indicatori di rischio, aiuti di Stato e sedi di aziende note. - name: Governance description: Proprietà, dirigenti, titolari effettivi e gruppo. - name: Financials description: Voci di bilancio, bilanci riclassificati, indici e grafico spider. - name: Composite description: Aziende comparabili. - name: Search description: Le aziende di un insieme filtrato, riga per riga. - name: Market description: Aggregati su un insieme filtrato. - name: Catalog description: Dati di riferimento gratuiti. paths: /market/base: post: tags: - Market summary: Dieci metriche su un insieme di aziende, con statistiche complete. description: >- Prezzo: 150 crediti, +50 con una ripartizione (area macro o classe dimensionale; una volta per chiamata, quanti che siano i gruppi). 404, mai addebitato, quando nessuna azienda dell'insieme ha depositato per l'anno. Di sola lettura e idempotente: si usa POST solo perché la richiesta ha un corpo. Il metodo HTTP QUERY è il verbo preferito per questa operazione e verrà accettato sullo stesso percorso quando il supporto dei client sarà diffuso. operationId: market-base requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MarketRequest' responses: '200': description: Dieci metriche su un insieme di aziende, con statistiche complete. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/MarketBase' meta: $ref: '#/components/schemas/ResponseMeta' required: - data - meta '401': description: missing_api_key | invalid_api_key content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: credits_exhausted | limit_reached content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: client_not_configured | not_entitled content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: unknown_endpoint | not_found content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: payload_too_large content: application/json: schema: $ref: '#/components/schemas/Error' '415': description: unsupported_media_type content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: invalid_params content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: rate_limited headers: Retry-After: description: >- Secondi da attendere prima di riprovare. Né un 429 né un 504 vengono addebitati. Un 504 la cui query aveva raggiunto il servizio dati lo lascia in esecuzione, e la sua risposta viene messa in cache, quindi la stessa chiamata dopo questo intervallo è di solito veloce. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: internal_error content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: upstream_error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: auth_unavailable | entitlement_unavailable content: application/json: schema: $ref: '#/components/schemas/Error' '504': description: upstream_timeout headers: Retry-After: description: >- Secondi da attendere prima di riprovare. Né un 429 né un 504 vengono addebitati. Un 504 la cui query aveva raggiunto il servizio dati lo lascia in esecuzione, e la sua risposta viene messa in cache, quindi la stessa chiamata dopo questo intervallo è di solito veloce. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: MarketRequest: type: object properties: year: type: integer minimum: 2015 maximum: 2100 description: Sempre obbligatorio. filters: $ref: '#/components/schemas/Filters' seedId: type: string minLength: 1 maxLength: 100 description: >- Un companyId o codice fiscale da cui ricavare l'insieme: la sua classe NACE, la sua area macro (Italia per la dimensione L) e la sua classe dimensionale. `filters` sovrascrive qualsiasi parte. breakdown: type: string enum: - none - macro - size description: >- Un asse per chiamata (predefinito nessuno): area macro (5 gruppi NUTS 1) o classe dimensionale (4 gruppi: XS, S, M, L) - mai entrambi. `macro` fallisce con 422 quando l'insieme ha già una geografia: un filtro `nuts` o `lau`, o un seed sotto la dimensione L. `size` fallisce con 422 quando l'insieme ha già una dimensione: un filtro `financial.size`, o qualsiasi seed. Non esiste una ripartizione regionale: per una regione o un'area macro, filtra su di essa, una chiamata per area. language: type: string enum: - it - en description: >- Lingua di nomi, etichette e descrizioni delle metriche (mai dei nomi dei campi o degli slug). Omessa: la lingua predefinita dell'account. required: - year additionalProperties: false description: >- Omettere sia `filters` sia `seedId`, o inviare `filters: {}`, aggrega tutte le aziende con un bilancio per `year` (tutta l'Italia), allo stesso prezzo. Più codici geografici in `filters.anagraphic.nuts` sono sommati in un unico insieme, mai separati. MarketBase: type: object properties: perimeter: $ref: '#/components/schemas/MarketPerimeter' market: $ref: '#/components/schemas/MarketBaseAggregate' groups: type: - array - 'null' items: $ref: '#/components/schemas/MarketBaseGroup' description: >- Null senza ripartizione. Altrimenti ogni gruppo - 5 aree macro o 4 classi dimensionali - in quell'ordine fisso, anche quelli vuoti (companyCount 0). required: - perimeter - market - groups description: >- Dieci metriche sull'insieme con statistiche complete; numero di aziende, dipendenti e radar sono inclusi. ResponseMeta: type: object properties: requestId: type: string endpoint: type: string usage: $ref: '#/components/schemas/Usage' warnings: type: array items: $ref: '#/components/schemas/Warning' description: Vuoto quando non ce ne sono. required: - requestId - endpoint - usage - warnings Error: type: object properties: error: type: object properties: code: type: string enum: - missing_api_key - invalid_api_key - credits_exhausted - limit_reached - client_not_configured - not_entitled - unknown_endpoint - not_found - payload_too_large - unsupported_media_type - invalid_params - rate_limited - internal_error - upstream_error - auth_unavailable - entitlement_unavailable - upstream_timeout message: type: string requestId: type: string details: type: array items: type: object properties: path: type: string message: type: string required: - path - message required: - code - message - requestId required: - error Filters: type: object properties: companyIds: type: array items: type: string maxLength: 100 minItems: 1 maxItems: 200 description: 'Limita a questi companyId (es. un portafoglio). Livello: base.' statementBasis: type: string enum: - individual - consolidated description: >- Quali bilanci includere: individuale (predefinito) o consolidato. Con companyIds decidono gli id. anagraphic: $ref: '#/components/schemas/AnagraphicFilter' financial: $ref: '#/components/schemas/FinancialFilter' stateAids: $ref: '#/components/schemas/StateAidsFilter' people: $ref: '#/components/schemas/PeopleFilter' radar: $ref: '#/components/schemas/RadarFilter' additionalProperties: false description: >- Definisce un insieme di aziende: /companies/search lo restituisce riga per riga, /market lo aggrega. Ogni sezione è facoltativa; tutto è in AND. MarketPerimeter: type: object properties: method: type: string enum: - filters - seed nace: type: array items: type: string geography: type: array items: type: string size: type: array items: $ref: '#/components/schemas/SizeBand' year: type: integer companyCount: type: integer description: >- Aziende dell'insieme per `year`: quelle con valori per quell'anno, depositati o ancora stimati - solo quelle depositate quando l'insieme filtra sui valori (filtri finanziari o radar). companiesWithFiling: type: integer description: >- Di queste, quante hanno depositato per `year`. Ogni valore è calcolato su queste. seedCompanyId: type: - string - 'null' matchCutoffApplied: type: - number - 'null' description: >- Impostato quando l'insieme usa la ricerca semantica; senza di essa i numeri non sono riproducibili. breakdown: type: string enum: - none - macro - size description: La ripartizione applicata. required: - method - nace - geography - size - year - companyCount - companiesWithFiling - seedCompanyId - matchCutoffApplied - breakdown MarketBaseAggregate: type: object properties: employees: $ref: '#/components/schemas/MarketStats' radar: $ref: '#/components/schemas/MarketRadar' metrics: type: array items: $ref: '#/components/schemas/MarketBaseMetric' minItems: 10 maxItems: 10 description: Le 10 metriche di `MarketBaseMetricSlug`, in quell'ordine. required: - employees - radar - metrics MarketBaseGroup: type: object properties: groupKey: type: string description: >- Codice NUTS 1 (ITC, ITH, ITI, ITF, ITG) con `macro`; XS, S, M o L con `size`. groupLabel: type: string description: Localizzato. companyCount: type: integer minimum: 0 market: $ref: '#/components/schemas/MarketBaseAggregate' required: - groupKey - groupLabel - companyCount - market Usage: type: object properties: quantity: type: number unit: type: string required: - quantity - unit Warning: type: object properties: code: type: string message: type: string required: - code - message AnagraphicFilter: type: object properties: name: type: object properties: contains: type: string maxLength: 200 startsWith: type: string maxLength: 200 additionalProperties: false minProperties: 1 maxProperties: 1 description: >- Filtro sulla denominazione, senza distinzione tra maiuscole e minuscole: `contains` cerca parole intere, `startsWith` un prefisso. Filtra, non ordina. Livello: base. nace: type: array items: type: string maxLength: 11 minItems: 1 maxItems: 20 description: >- Codici NACE, tutti allo stesso livello: sezione `C`, divisione `27`, gruppo `27.9`, classe `27.90`, sottocategoria `27.90.01`. Livello: base. nuts: type: array items: type: string minLength: 3 maxLength: 5 minItems: 1 maxItems: 20 description: >- Codici NUTS, tutti allo stesso livello (3 caratteri = area macro, 4 = regione, 5 = provincia). Corrisponde alla sede legale, non alle sedi operative. Livello: base. lau: type: array items: type: string maxLength: 12 minItems: 1 maxItems: 50 description: 'Codici ISTAT del comune della sede legale. Livello: base.' countryCode: type: string pattern: ^[A-Z]{2}$ description: 'ISO 3166-1 alpha-2. Livello: base.' age: type: object properties: min: type: integer max: type: integer additionalProperties: false description: >- Età dell'azienda, in anni. Livello: base. Limiti inclusivi: min, max o entrambi, con min <= max. minProperties: 1 semanticSearch: type: string minLength: 1 maxLength: 500 description: >- Ricerca sulla descrizione dell'ATTIVITÀ (prodotti, servizi, mercati serviti) - non su nome, forma giuridica o dati finanziari. Livello: plus. matchCutoff: type: number minimum: 0.5 maximum: 1 description: >- Similarità semantica minima, predefinita 0,8. Più alta = meno corrispondenze, più vicine. Livello: plus. shareholderAge: type: object properties: min: type: integer max: type: integer additionalProperties: false description: >- Età MEDIA dei soci, in anni. Livello: pro. Limiti inclusivi: min, max o entrambi, con min <= max. minProperties: 1 beneficialOwnerAge: type: object properties: min: type: integer max: type: integer additionalProperties: false description: >- Età MEDIA dei titolari effettivi, in anni - non del socio di maggioranza. Livello: pro. Limiti inclusivi: min, max o entrambi, con min <= max. minProperties: 1 executiveOfficerAge: type: object properties: min: type: integer max: type: integer additionalProperties: false description: >- Età media dei dirigenti, in anni. Livello: pro. Limiti inclusivi: min, max o entrambi, con min <= max. minProperties: 1 representationAndAuthorityOfficerAge: type: object properties: min: type: integer max: type: integer additionalProperties: false description: >- Età media di chi ha poteri di rappresentanza, in anni. Livello: pro. Limiti inclusivi: min, max o entrambi, con min <= max. minProperties: 1 targetMarket: type: array items: $ref: '#/components/schemas/TargetMarket' minItems: 1 maxItems: 9 description: >- Serve QUALSIASI di questi canali (valori esatti: B2B non è B2B2C). Livello: pro. controllingEntityCategory: type: array items: $ref: '#/components/schemas/ControllingEntityCategory' minItems: 1 maxItems: 6 description: >- Controllata da QUALSIASI di queste categorie di entità. Livello: pro. additionalProperties: false description: Profilo dell'azienda. Non richiede `year`. FinancialFilter: type: object properties: size: type: array items: $ref: '#/components/schemas/SizeBand' minItems: 1 maxItems: 4 description: 'Classe dimensionale UE. Livello: base.' employees: type: object properties: min: type: integer max: type: integer additionalProperties: false description: >- Numero di dipendenti. Livello: base. Limiti inclusivi: min, max o entrambi, con min <= max. minProperties: 1 revenue: type: object properties: min: type: number max: type: number additionalProperties: false description: >- Ricavi da vendite e prestazioni, EUR. Livello: base. Limiti inclusivi: min, max o entrambi, con min <= max. minProperties: 1 metricFilters: type: array items: $ref: '#/components/schemas/MetricFilter' minItems: 1 maxItems: 10 description: 'Fino a dieci condizioni su metriche, in AND. Livello: plus.' additionalProperties: false description: Richiede `year` nella richiesta. StateAidsFilter: type: object properties: totalAmount: type: object properties: min: type: number max: type: number additionalProperties: false description: >- Aiuti di Stato ricevuti, di sempre, ogni regime, EUR. Limiti inclusivi: min, max o entrambi, con min <= max. minProperties: 1 amountLast36Months: type: object properties: min: type: number max: type: number additionalProperties: false description: >- Aiuti di Stato ricevuti negli ultimi 36 mesi, EUR. Limiti inclusivi: min, max o entrambi, con min <= max. minProperties: 1 countLast36Months: type: object properties: min: type: integer max: type: integer additionalProperties: false description: >- Aiuti di Stato concessi negli ultimi 36 mesi. Limiti inclusivi: min, max o entrambi, con min <= max. minProperties: 1 aboveSectorMedianLast36Months: type: boolean deMinimisRemaining: type: object properties: min: type: number max: type: number additionalProperties: false description: >- Margine residuo prima del massimale de minimis, EUR. `{min: 1}` = può ancora riceverne. Limiti inclusivi: min, max o entrambi, con min <= max. minProperties: 1 lastGrantDate: type: object properties: after: type: string format: date before: type: string format: date additionalProperties: false description: >- Data dell'ultima concessione. Date ISO inclusive: after, before o entrambe. minProperties: 1 additionalProperties: false description: >- Livello: plus. Non richiede `year` (il riepilogo degli aiuti è cumulativo, non per anno). minProperties: 1 PeopleFilter: type: object properties: officers: type: array items: type: object properties: personId: type: string maxLength: 100 roleCategory: $ref: '#/components/schemas/RoleCategory' required: - personId additionalProperties: false minItems: 1 maxItems: 20 shareholderIds: type: array items: type: string maxLength: 100 minItems: 1 maxItems: 20 beneficialOwnerIds: type: array items: type: string maxLength: 100 minItems: 1 maxItems: 20 additionalProperties: false description: >- Livello: pro. All'interno di una lista vale QUALSIASI corrispondenza; tra liste devono valere TUTTE. Gli id delle persone provengono da /companies/structure. minProperties: 1 RadarFilter: type: object properties: size: type: object properties: min: type: number max: type: number additionalProperties: false description: >- Asse dimensione del radar, 0-100. Limiti inclusivi: min, max o entrambi, con min <= max. minProperties: 1 efficiency: type: object properties: min: type: number max: type: number additionalProperties: false description: >- Asse efficienza del radar, 0-100. Limiti inclusivi: min, max o entrambi, con min <= max. minProperties: 1 polygon: type: object properties: vertices: type: array items: type: object properties: size: type: number minimum: 0 maximum: 100 efficiency: type: number minimum: 0 maximum: 100 required: - size - efficiency additionalProperties: false minItems: 3 maxItems: 64 required: - vertices additionalProperties: false description: Qualsiasi regione del piano; l'ordine dei vertici non conta. additionalProperties: false description: >- Livello: plus. Richiede `year`. Confrontabile tra settori. Almeno uno dei tre. minProperties: 1 SizeBand: type: string enum: - XS - S - M - L description: >- Classe dimensionale UE del record di bilancio (non del gruppo, salvo se consolidato). MarketStats: type: object properties: count: type: integer description: >- Aziende con QUESTA metrica valorizzata - non companyCount. Le quote usano la popolazione, le mediane questo conteggio. average: type: - number - 'null' median: type: - number - 'null' p10: type: - number - 'null' p90: type: - number - 'null' min: type: - number - 'null' max: type: - number - 'null' stdDev: type: - number - 'null' sum: type: - number - 'null' description: >- Null dove un totale non è una grandezza reale (percentuali, rapporti, giorni, radar). required: - count - average - median - p10 - p90 - min - max - stdDev - sum MarketRadar: type: object properties: efficiencyAvg: type: - number - 'null' efficiencyMedian: type: - number - 'null' sizeAvg: type: - number - 'null' sizeMedian: type: - number - 'null' required: - efficiencyAvg - efficiencyMedian - sizeAvg - sizeMedian MarketBaseMetric: allOf: - $ref: '#/components/schemas/MarketMetric' - type: object properties: slug: $ref: '#/components/schemas/MarketBaseMetricSlug' TargetMarket: type: string enum: - B2B - B2C - B2G - B2B2C - B2B2G - C2C - C2B - G2C - G2B ControllingEntityCategory: type: string enum: - FAMILY - FAMILY_OWNED_GROUP - FINANCIALLY_OWNED_GROUP - INDUSTRIAL_GROUP - FINANCIAL - OTHER MetricFilter: type: object properties: slug: $ref: '#/components/schemas/MetricSlug' min: type: number description: Sul valore grezzo, scala nativa. max: type: number scoreMin: type: integer minimum: 1 maximum: 5 description: >- Punteggio da 1 a 5 rispetto al mercato dell'azienda (5 è sempre il migliore). Solo un criterio di selezione - i punteggi non vengono mai restituiti. Le aziende senza punteggio sono escluse da qualsiasi limite sul punteggio. scoreMax: type: integer minimum: 1 maximum: 5 required: - slug additionalProperties: false description: >- Lo slug più almeno un limite; i limiti sul valore e sul punteggio di una stessa voce sono in AND. minProperties: 2 RoleCategory: type: string enum: - GOVERNING_BODIES - ADMINISTRATION_AND_EXECUTIVES - AUDITING - REPRESENTATION_AND_AUTHORITY - EXTRAORDINARY_PROCEDURES - FUNCTIONAL_ROLES - PARTICIPATION_OWNERSHIP - CHIEF_EXECUTIVE_OFFICER - OTHER MarketMetric: type: object properties: slug: $ref: '#/components/schemas/MetricSlug' name: type: string unit: $ref: '#/components/schemas/MetricUnit' stats: $ref: '#/components/schemas/MarketStats' required: - slug - name - unit - stats MarketBaseMetricSlug: type: string enum: - revenues_from_sales_and_services - ebitda - added_value - ebitda_margin - ebit_margin - revenue_cagr_3_years - added_value_employee - equity_ratio - net_financial_position_ebitda - capex_sales_ratio description: >- Le dieci metriche Base, sempre tutte restituite, in quest'ordine: dimensione (ricavi, EBITDA, valore aggiunto), redditività (margine EBITDA ed EBIT), crescita (CAGR dei ricavi a 3 anni), produttività (valore aggiunto per dipendente), solidità (indice di patrimonializzazione, PFN/EBITDA), investimenti (capex sui ricavi). MetricSlug: type: string enum: - revenues_from_sales_and_services - value_of_production - profit - added_value - ebitda - ebit - added_value_employee - ebitda_margin - ebit_margin - roe - roa - sales_assets - revenue_cagr_3_years - ebitda_cagr_3_years - personnel_cost_to_revenue - raw_materials_contribution - services_and_leases_contribution - net_working_capital - ufcf - cash_ratio - quick_ratio - secondary_liquidity - days_sales_outstanding - days_sales_outstanding_commercial_receivables - days_payable_outstanding - dpo_commercial_debt - days_sales_inventory - cash_conversion_cycle - cash_conversion_cycle_commercial - net_financial_position - current_net_financial_position - net_financial_position_ebitda - debt_ebitda_ratio - indeb_ratio - financial_leverage - over_indebtedness_ratio - interest_coverage_ratio_ebitda_based - debt_service_cover_ratio_ebitda_version - debt_service_cover_ratio_cash_flow_based - cost_borrowed_money - financial_sustainability - financial_charges_on_nfp - capex - invested_capital - equity_ratio - self_coverage - financial_debt_net_worth - non_curr_liabilities_fixed_asset_ratio - capex_sales_ratio - debt_on_revenue - short_term_debt_on_revenue - current_debt_to_total_debt_ratio - curr_asset_total_asset_ratio - cash_curr_asset_ratio - tfr_contribution description: >- Uno dei 55 indici; GET /metrics (gratuito) li elenca con nomi, unità e formule. Gli slug fanno parte del contratto; i nomi sono localizzati. MetricUnit: type: string enum: - eur - pct - ratio - days - eur_per_head - count description: >- `pct` è una frazione, mai moltiplicata: 0,15 equivale al 15%, e può superare 1 o essere negativa. `eur_per_head` è euro per dipendente. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Chiave API di organizzazione WorkOS (sk_...), inviata come `Authorization: Bearer `. Gli admin creano e revocano le chiavi nella dashboard Syrto: https://dashboard.syrto.ai/api-keys ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.