> ## 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. # Search > Price per company RETURNED, at the tier of the most advanced filter used: base 3, plus 6, pro 10 credits (+10 each with echoFilters). An empty page costs nothing. Set `maxTier` to cap the tier. Read-only and idempotent: POST is used only because the request carries a body. The HTTP QUERY method is the preferred verb for this operation and will be accepted on the same path once client support is widespread. ## OpenAPI ````yaml api-reference/openapi.standard.json POST /companies/search openapi: 3.1.0 info: title: Syrto API - standard endpoints version: 1.7.0 description: >- Financial, corporate and market data on Italian companies. Every call answers `200 { data, meta }`; `meta.usage.quantity` is what the call consumed, in credits, and `meta.warnings` lists any non-fatal caveats (empty when there are none). Every field is always present and unknown values are null. Percentages are fractions (0.15 = 15%). **Authentication.** Every call needs an API key, sent as `Authorization: Bearer sk_...` over HTTPS - never in a URL. Keys are scoped to your organization: admins create and revoke them in the Syrto dashboard (https://dashboard.syrto.ai/api-keys). A missing or unrecognised key is a 401 (`missing_api_key`, `invalid_api_key`); a 503 `auth_unavailable` means the key could not be checked right now, so retry with backoff rather than rotating it. **Billing basis.** negativities, rna and structure bill once per legal entity: the individual and consolidated records of the same company count once. Every other endpoint bills per record (or per call), so individual and consolidated count separately. A tax id always resolves to a single record (`statementBasis`, individual by default): a company is billed twice only when both of its companyIds are passed. A market call is priced per call, whatever the size of its set: omitting `filters` and `seedId`, or sending `filters: {}`, is the whole of Italy, at the same price. notFound entries are never billed, and neither is any error. servers: - url: https://api.syrto.ai security: [] tags: - name: Company data description: Identity, risk flags, state aid and branches of known companies. - name: Governance description: Ownership, officers, beneficial owners and group. - name: Financials description: Statement items, reclassified statements, indices and spider graph. - name: Composite description: Comparable companies. - name: Search description: The companies of a filtered set, row by row. - name: Market description: Aggregates over a filtered set. - name: Catalog description: Free reference data. paths: /companies/search: post: tags: - Search summary: The companies of a filtered set, one row each, up to 200 per page. description: >- Price per company RETURNED, at the tier of the most advanced filter used: base 3, plus 6, pro 10 credits (+10 each with echoFilters). An empty page costs nothing. Set `maxTier` to cap the tier. Read-only and idempotent: POST is used only because the request carries a body. The HTTP QUERY method is the preferred verb for this operation and will be accepted on the same path once client support is widespread. operationId: company-search requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CompanySearchRequest' responses: '200': description: The companies of a filtered set, one row each, up to 200 per page. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CompanySearchResult' 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: >- Seconds to wait before retrying. Neither a 429 nor a 504 is billed. A 504 whose query had reached the data service leaves it running, and its answer is cached, so the same call after this delay is usually fast. 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: >- Seconds to wait before retrying. Neither a 429 nor a 504 is billed. A 504 whose query had reached the data service leaves it running, and its answer is cached, so the same call after this delay is usually fast. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: CompanySearchRequest: type: object properties: filters: $ref: '#/components/schemas/Filters' year: type: integer minimum: 2015 maximum: 2100 description: Required with financial or radar filters, or a metric sort. limit: type: integer minimum: 1 maximum: 200 description: >- Companies per page, 1-200 (default 200). Billed per company returned. after: type: string maxLength: 512 description: Opaque cursor from `endCursor`. sortBy: type: object properties: field: type: string enum: - matchScore - metric metricSlug: $ref: '#/components/schemas/MetricSlug' direction: type: string enum: - asc - desc required: - field additionalProperties: false description: >- Omitted: legal name, A-Z. `matchScore` needs `semanticSearch`; `metric` needs `metricSlug` (one of the indices listed by GET /metrics) and `year`, and sorts on that year's value. `direction` defaults to `desc` (best match or highest value first). Never by score. echoFilters: type: boolean description: >- Return each company's values for the filtered fields (+10 credits per company). maxTier: type: string enum: - base - plus - pro description: >- Spending guard: a filter above this tier fails the call with 422, before anything is billed. language: type: string enum: - it - en description: >- Language of metric names, labels and descriptions (never of field names or slugs). Omitted: the account's default. required: - filters additionalProperties: false CompanySearchResult: type: object properties: totalCount: type: - integer - 'null' minimum: 0 description: >- Companies in the whole set. Null on an empty page reached with `after`: an unbilled page does not count the set. returnedCount: type: integer minimum: 0 tierApplied: $ref: '#/components/schemas/SearchTier' hasNextPage: type: boolean endCursor: type: - string - 'null' items: type: array items: $ref: '#/components/schemas/CompanySearchItem' required: - totalCount - returnedCount - tierApplied - hasNextPage - endCursor - items ResponseMeta: type: object properties: requestId: type: string endpoint: type: string usage: $ref: '#/components/schemas/Usage' warnings: type: array items: $ref: '#/components/schemas/Warning' description: Empty when there are none. 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: 'Restrict to these companyIds (e.g. a portfolio). Tier: base.' statementBasis: type: string enum: - individual - consolidated description: >- Which statements to include: individual (default) or consolidated. With companyIds, the ids decide. 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: >- Defines a set of companies: /companies/search returns it row by row, /market aggregates it. Every section is optional; everything is ANDed. 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: >- One of the 55 indices; GET /metrics (free) lists them with their names, units and formulas. Slugs are part of the contract; names are localized. SearchTier: type: string enum: - base - plus - pro description: >- Set by the most advanced filter used, never by the fields returned: base = profile, geography, size, revenue; plus = semantic, metric, radar and state-aid filters; pro = people, owner ages, control type, channels. CompanySearchItem: allOf: - $ref: '#/components/schemas/CompanyHeader' - type: object properties: year: type: - integer - 'null' financialStatementDate: type: - string - 'null' format: date description: >- Date of the financial statement the figures come from: the financial year end it is made up to (data di chiusura dell'esercizio - 31 December for most companies, 30 June for a club closing in June). Cite it when reporting a discrepancy. activityOverview: type: - string - 'null' naceClass: type: - string - 'null' nuts1: type: - string - 'null' nuts2: type: - string - 'null' nuts3: type: - string - 'null' lau: type: - string - 'null' sizeClassification: anyOf: - $ref: '#/components/schemas/SizeBand' - type: 'null' employeeCount: type: - integer - 'null' matchScore: type: - number - 'null' description: Set only with semanticSearch. filteredValues: type: - object - 'null' additionalProperties: {} description: >- With echoFilters: the company's value for each filtered field. Never scores. required: - year - financialStatementDate - activityOverview - naceClass - nuts1 - nuts2 - nuts3 - lau - sizeClassification - employeeCount - matchScore - filteredValues 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: >- Legal-name screen, case-insensitive: `contains` matches whole words, `startsWith` a prefix. Filters, never ranks. Tier: base. nace: type: array items: type: string maxLength: 11 minItems: 1 maxItems: 20 description: >- NACE codes, all at one level: section `C`, division `27`, group `27.9`, class `27.90`, subclass `27.90.01`. Tier: base. nuts: type: array items: type: string minLength: 3 maxLength: 5 minItems: 1 maxItems: 20 description: >- NUTS codes, all at one level (3 chars = macro area, 4 = region, 5 = province). Matches the registered office, not operating sites. Tier: base. lau: type: array items: type: string maxLength: 12 minItems: 1 maxItems: 50 description: 'ISTAT municipality codes of the registered office. Tier: base.' countryCode: type: string pattern: ^[A-Z]{2}$ description: 'ISO 3166-1 alpha-2. Tier: base.' age: type: object properties: min: type: integer max: type: integer additionalProperties: false description: >- Company age, in years. Tier: base. Inclusive bounds: min, max or both, with min <= max. minProperties: 1 semanticSearch: type: string minLength: 1 maxLength: 500 description: >- Search on the ACTIVITY description (products, services, markets served) - not name, legal form or financials. Tier: plus. matchCutoff: type: number minimum: 0.5 maximum: 1 description: >- Minimum semantic similarity, default 0.8. Higher is fewer, closer matches. Tier: plus. shareholderAge: type: object properties: min: type: integer max: type: integer additionalProperties: false description: >- AVERAGE age of the shareholders, in years. Tier: pro. Inclusive bounds: min, max or both, with min <= max. minProperties: 1 beneficialOwnerAge: type: object properties: min: type: integer max: type: integer additionalProperties: false description: >- AVERAGE age of the beneficial owners, in years - not the majority holder's. Tier: pro. Inclusive bounds: min, max or both, with min <= max. minProperties: 1 executiveOfficerAge: type: object properties: min: type: integer max: type: integer additionalProperties: false description: >- Average age of the executive officers, in years. Tier: pro. Inclusive bounds: min, max or both, with min <= max. minProperties: 1 representationAndAuthorityOfficerAge: type: object properties: min: type: integer max: type: integer additionalProperties: false description: >- Average age of those with powers of representation, in years. Tier: pro. Inclusive bounds: min, max or both, with min <= max. minProperties: 1 targetMarket: type: array items: $ref: '#/components/schemas/TargetMarket' minItems: 1 maxItems: 9 description: >- Serves ANY of these channels (exact values: B2B is not B2B2C). Tier: pro. controllingEntityCategory: type: array items: $ref: '#/components/schemas/ControllingEntityCategory' minItems: 1 maxItems: 6 description: 'Controlled by ANY of these entity categories. Tier: pro.' additionalProperties: false description: Company profile. Needs no `year`. FinancialFilter: type: object properties: size: type: array items: $ref: '#/components/schemas/SizeBand' minItems: 1 maxItems: 4 description: 'EU size class. Tier: base.' employees: type: object properties: min: type: integer max: type: integer additionalProperties: false description: >- Employee count. Tier: base. Inclusive bounds: min, max or both, with min <= max. minProperties: 1 revenue: type: object properties: min: type: number max: type: number additionalProperties: false description: >- Revenues from sales and services, EUR. Tier: base. Inclusive bounds: min, max or both, with min <= max. minProperties: 1 metricFilters: type: array items: $ref: '#/components/schemas/MetricFilter' minItems: 1 maxItems: 10 description: 'Up to ten metric conditions, ANDed. Tier: plus.' additionalProperties: false description: Needs `year` on the request. StateAidsFilter: type: object properties: totalAmount: type: object properties: min: type: number max: type: number additionalProperties: false description: >- State aid received, all time, every regime, EUR. Inclusive bounds: min, max or both, with min <= max. minProperties: 1 amountLast36Months: type: object properties: min: type: number max: type: number additionalProperties: false description: >- State aid received in the trailing 36 months, EUR. Inclusive bounds: min, max or both, with min <= max. minProperties: 1 countLast36Months: type: object properties: min: type: integer max: type: integer additionalProperties: false description: >- State aid grants in the trailing 36 months. Inclusive bounds: min, max or both, with min <= max. minProperties: 1 aboveSectorMedianLast36Months: type: boolean deMinimisRemaining: type: object properties: min: type: number max: type: number additionalProperties: false description: >- Allowance left before the de minimis ceiling, EUR. `{min: 1}` = can still receive. Inclusive bounds: min, max or both, with min <= max. minProperties: 1 lastGrantDate: type: object properties: after: type: string format: date before: type: string format: date additionalProperties: false description: >- Date of the latest grant. Inclusive ISO dates: after, before or both. minProperties: 1 additionalProperties: false description: >- Tier: plus. Needs no `year` (the aid summary is cumulative, not per year). 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: >- Tier: pro. Within a list ANY matches; across lists ALL must. Person ids come from /companies/structure. minProperties: 1 RadarFilter: type: object properties: size: type: object properties: min: type: number max: type: number additionalProperties: false description: >- Radar size axis, 0-100. Inclusive bounds: min, max or both, with min <= max. minProperties: 1 efficiency: type: object properties: min: type: number max: type: number additionalProperties: false description: >- Radar efficiency axis, 0-100. Inclusive bounds: min, max or both, with 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: Any region of the plane; vertex order does not matter. additionalProperties: false description: >- Tier: plus. Needs `year`. Comparable across sectors. At least one of the three. minProperties: 1 CompanyHeader: type: object properties: companyId: type: string description: >- Syrto id of this statement record. Individual and consolidated differ. legalName: type: - string - 'null' taxId: type: - string - 'null' description: Codice fiscale / partita IVA. consolidated: type: boolean description: Whether these figures are the consolidated (group) statement. required: - companyId - legalName - taxId - consolidated SizeBand: type: string enum: - XS - S - M - L description: >- EU size class of the statement record (not of the group, unless consolidated). 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: On the raw value, native scale. max: type: number scoreMin: type: integer minimum: 1 maximum: 5 description: >- 1-5 score against the company's market (5 is always best). A selection criterion only - scores are never returned. Companies without a score are excluded by any score bound. scoreMax: type: integer minimum: 1 maximum: 5 required: - slug additionalProperties: false description: >- The slug plus at least one bound; value and score bounds on one entry are ANDed. 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 securitySchemes: bearerAuth: type: http scheme: bearer description: >- Org-scoped WorkOS API key (sk_...), sent as `Authorization: Bearer `. Admins create and revoke keys in the Syrto dashboard: https://dashboard.syrto.ai/api-keys ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.