# Authentication
Source: https://docs.syrto.ai/api/authentication

Authenticate to the Syrto API with a bearer API key.

Every endpoint requires an API key. The same key identifies you and determines which endpoints you can call.

## Getting a key

Once Syrto has provisioned an API for your organization, admins create and revoke API keys in the [Syrto dashboard](https://dashboard.syrto.ai/api-keys). Each key is scoped to your organization.

## Sending your key

Pass the key as a bearer token in the `Authorization` header:

```
Authorization: Bearer sk_...
```

Keys begin with `sk_`. Keep them secret - a key grants access to your data and consumes your usage. Send every request over HTTPS, and never place a key in a URL.

The examples in these docs read the key from a `SYRTO_API_KEY` environment variable, so you can export it once and run any example:

```bash theme={null}
export SYRTO_API_KEY=sk_...

curl -s -H "Authorization: Bearer $SYRTO_API_KEY" \
  https://api.syrto.ai/companies/01654010345/financials
```

## Authentication errors

| Code               | HTTP  | When                                                                                          |
| ------------------ | ----- | --------------------------------------------------------------------------------------------- |
| `missing_api_key`  | `401` | No `Authorization` header, or it isn't a bearer token.                                        |
| `invalid_api_key`  | `401` | The key is not recognised.                                                                    |
| `auth_unavailable` | `503` | Key validation is temporarily unavailable. Retry after a short wait - do not rotate your key. |

<Warning>
  A `503 auth_unavailable` means the service could not verify your key right now, not that your key is wrong. Retry with backoff; rotating the key won't help.
</Warning>

Each error response follows the standard [error envelope](/api/errors):

```json theme={null}
{
  "error": {
    "code": "missing_api_key",
    "message": "Missing API key.",
    "requestId": "req_018f9c2e7b7a7c3e9a1b2c3d4e5f6a7b"
  }
}
```

## Your endpoints and spec

Your key is scoped to the endpoints included in your plan. To see exactly which endpoints and schemas your key can access, fetch your own [OpenAPI spec](/api/openapi) - it is generated per key and contains only the endpoints you're offered.


# Credit report
Source: https://docs.syrto.ai/api/endpoints/company-credit-report

A full credit report for an Italian company by fiscal code - identity, risk, ownership, officers, and recent financials.

Returns a full credit report for one company: identity and registry data, risk indicators, headcount, state aids, ownership and officers, and several recent years of headline financials. Ownership and officers carry names only, with no other personal identifiers.

<Info>
  Example endpoint. Whether it is part of your API depends on your organization's configuration - check [your schema](/api/openapi) for the endpoints provisioned for you.
</Info>

```
GET /companies/{fiscalCode}/credit-report
```

## Path parameters

<ParamField type="string">
  The company's Italian fiscal code - either an 11-digit tax/VAT code or a 16-character codice fiscale. Case-insensitive.
</ParamField>

## Usage

Each successful call records a default measure of **10 credits**. The exact measure billed is always returned in `meta.usage` and may differ under your plan.

## Response

The `data` object contains:

<ResponseField name="id" type="string">Syrto's internal company identifier.</ResponseField>
<ResponseField name="isConsolidated" type="boolean">Whether the figures come from consolidated financial statements.</ResponseField>
<ResponseField name="latestFiledYear" type="number | null">The most recent fiscal year with filed figures.</ResponseField>

<ResponseField name="identity" type="CompanyIdentity">
  Descriptive company information (see [CompanyIdentity](/api/objects#companyidentity)), plus:

  * `foreignOwned` (`boolean | null`) - whether the company is foreign-owned.
  * `controllingEntity` (`string | null`) - the controlling entity, if any.
</ResponseField>

<ResponseField name="registry" type="object | null">
  Registry contacts, or `null`:

  * `pec` (`string | null`) - certified email address.
  * `cciaa` (`string | null`) - Chamber of Commerce registration.
  * `rea` (`string | null`) - REA number.
</ResponseField>

<ResponseField name="headcount" type="object | null">
  `null`, or `{ employees: number, asOf: string }` - employee count and the date it refers to.
</ResponseField>

<ResponseField name="risk" type="RiskIndicators">Risk flags. See [RiskIndicators](/api/objects#riskindicators).</ResponseField>

<ResponseField name="stateAids" type="object | null">
  State aid totals, or `null`. Fields `count`, `countLast36Months`, `amount`, `amountLast36Months` (each `number | null`).
</ResponseField>

<ResponseField name="ownership" type="object[]">
  Shareholders, each `{ name: string | null, share: number | null }` where `share` is an ownership fraction.
</ResponseField>

<ResponseField name="officers" type="object[]">
  Officers, each `{ name: string | null, role: string | null, roleCategory: string }`.
</ResponseField>

<ResponseField name="latest" type="AnnualSnapshot | null">The latest year of headline figures. See [AnnualSnapshot](/api/objects#annualsnapshot).</ResponseField>
<ResponseField name="financials" type="AnnualSnapshot[]">Recent years of headline figures, newest first. See [AnnualSnapshot](/api/objects#annualsnapshot).</ResponseField>

## Example

```bash theme={null}
curl -H "Authorization: Bearer $SYRTO_API_KEY" \
  https://api.syrto.ai/companies/01654010345/credit-report
```

```json theme={null}
{
  "data": {
    "id": "Zm86SVRfMDE2NTQwMTAzNDVfVTox",
    "isConsolidated": false,
    "latestFiledYear": 2023,
    "identity": {
      "legalName": "BARILLA G. E R. FRATELLI - SOCIETÀ PER AZIONI",
      "legalForm": "S.p.A.",
      "foundingYear": 1877,
      "incorporationDate": "1877-01-01",
      "isQuoted": false,
      "vatNumber": "01654010345",
      "fiscalCode": "01654010345",
      "naceCode": "10.73",
      "naceSection": "C",
      "address": {
        "line1": "Via Mantova 166",
        "line2": null,
        "locality": "Parma",
        "postalCode": "43122",
        "countryCode": "IT"
      },
      "foreignOwned": false,
      "controllingEntity": null
    },
    "registry": {
      "pec": "barilla@pec.example.it",
      "cciaa": "PR-123456",
      "rea": "PR-123456"
    },
    "headcount": { "employees": 8760, "asOf": "2023-12-31" },
    "risk": {
      "protestsOfBill": false,
      "insolvencyProceedings": false,
      "insolvencyApplications": false,
      "assetEncumbrances": false,
      "officersWithRiskIndicators": false
    },
    "stateAids": {
      "count": 12,
      "countLast36Months": 3,
      "amount": 1450000,
      "amountLast36Months": 320000
    },
    "ownership": [
      { "name": "Barilla Holding S.p.A.", "share": 0.85 }
    ],
    "officers": [
      { "name": "Guido Barilla", "role": "Chairman", "roleCategory": "board" }
    ],
    "latest": {
      "year": 2023,
      "isForecasted": false,
      "size": "L",
      "statementDate": "2023-12-31",
      "employees": 8760,
      "employeesYoY": 0.03
    },
    "financials": [
      { "year": 2023, "isForecasted": false, "size": "L", "statementDate": "2023-12-31", "employees": 8760, "employeesYoY": 0.03 },
      { "year": 2022, "isForecasted": false, "size": "L", "statementDate": "2022-12-31", "employees": 8505, "employeesYoY": 0.02 }
    ]
  },
  "meta": {
    "requestId": "req_018f9c2e7b7a7c3e9a1b2c3d4e5f6a7b",
    "endpoint": "company-credit-report",
    "usage": { "quantity": 10, "unit": "credits" }
  }
}
```


# Company financials
Source: https://docs.syrto.ai/api/endpoints/company-financials

A financial snapshot for a single Italian company by tax ID.

Returns a financial snapshot for one company: its identity, whether its figures are consolidated, and its latest reported year of headline figures.

<Info>
  Example endpoint. Whether it is part of your API depends on your organization's configuration - check [your schema](/api/openapi) for the endpoints provisioned for you.
</Info>

```
GET /companies/{taxId}/financials
```

## Path parameters

<ParamField type="string">
  The company's Italian tax ID (codice fiscale). Any non-empty value.
</ParamField>

## Usage

Each successful call records a default measure of **5 credits**. The exact measure billed is always returned in `meta.usage` and may differ under your plan.

## Response

The `data` object contains:

<ResponseField name="id" type="string">Syrto's internal company identifier.</ResponseField>
<ResponseField name="isConsolidated" type="boolean">Whether the figures come from consolidated financial statements.</ResponseField>
<ResponseField name="latestFiledYear" type="number | null">The most recent fiscal year with filed figures.</ResponseField>
<ResponseField name="identity" type="CompanyIdentity">Descriptive company information. See [CompanyIdentity](/api/objects#companyidentity).</ResponseField>
<ResponseField name="latest" type="AnnualSnapshot | null">The latest year of headline figures. See [AnnualSnapshot](/api/objects#annualsnapshot).</ResponseField>

## Example

```bash theme={null}
curl -H "Authorization: Bearer $SYRTO_API_KEY" \
  https://api.syrto.ai/companies/01654010345/financials
```

```json theme={null}
{
  "data": {
    "id": "Zm86SVRfMDE2NTQwMTAzNDVfVTox",
    "isConsolidated": false,
    "latestFiledYear": 2023,
    "identity": {
      "legalName": "BARILLA G. E R. FRATELLI - SOCIETÀ PER AZIONI",
      "legalForm": "S.p.A.",
      "foundingYear": 1877,
      "incorporationDate": "1877-01-01",
      "isQuoted": false,
      "vatNumber": "01654010345",
      "fiscalCode": "01654010345",
      "naceCode": "10.73",
      "naceSection": "C",
      "address": {
        "line1": "Via Mantova 166",
        "line2": null,
        "locality": "Parma",
        "postalCode": "43122",
        "countryCode": "IT"
      }
    },
    "latest": {
      "year": 2023,
      "isForecasted": false,
      "size": "L",
      "statementDate": "2023-12-31",
      "employees": 8760,
      "employeesYoY": 0.03
    }
  },
  "meta": {
    "requestId": "req_018f9c2e7b7a7c3e9a1b2c3d4e5f6a7b",
    "endpoint": "company-financials",
    "usage": { "quantity": 5, "unit": "credits" }
  }
}
```


# Company profile
Source: https://docs.syrto.ai/api/endpoints/company-profile

A company profile that adapts to size - peers for large companies, a deeper risk view for smaller ones.

Returns a profile for one company. The response adapts to the company's size: large companies come with a peer comparison, and smaller companies come with a deeper risk view. One price covers the whole call regardless of which branch runs.

<Info>
  Example endpoint. Whether it is part of your API depends on your organization's configuration - check [your schema](/api/openapi) for the endpoints provisioned for you.
</Info>

```
GET /companies/{taxId}/profile
```

## Path parameters

<ParamField type="string">
  The company's Italian tax ID (codice fiscale). Any non-empty value.
</ParamField>

## Usage

Each successful call records a default measure of **8 credits**. The exact measure billed is always returned in `meta.usage` and may differ under your plan.

## Response

The `data` object always contains these base fields:

<ResponseField name="id" type="string">Syrto's internal company identifier.</ResponseField>
<ResponseField name="identity" type="CompanyIdentity">Descriptive company information. See [CompanyIdentity](/api/objects#companyidentity).</ResponseField>
<ResponseField name="latest" type="AnnualSnapshot | null">The latest year of headline figures. See [AnnualSnapshot](/api/objects#annualsnapshot).</ResponseField>

Then exactly one of the following branches is present, depending on the company's size.

### Large companies

<ResponseField name="peerCount" type="number">The number of comparable peers found.</ResponseField>

<ResponseField name="peers" type="object[]">
  Peer companies, each `{ id: string, identity: CompanyIdentity, latest: AnnualSnapshot | null }`.
</ResponseField>

### Smaller companies

<ResponseField name="risk" type="object">
  Risk flags (see [RiskIndicators](/api/objects#riskindicators)), plus:

  * `stateAids` (`object | null`) - `{ count, amount }` state aid totals.
  * `history` (`AnnualSnapshot[]`) - recent years of headline figures.
</ResponseField>

## Example

Large company (peer branch):

```bash theme={null}
curl -H "Authorization: Bearer $SYRTO_API_KEY" \
  https://api.syrto.ai/companies/01654010345/profile
```

```json theme={null}
{
  "data": {
    "id": "Zm86SVRfMDE2NTQwMTAzNDVfVTox",
    "identity": {
      "legalName": "BARILLA G. E R. FRATELLI - SOCIETÀ PER AZIONI",
      "legalForm": "S.p.A.",
      "foundingYear": 1877,
      "incorporationDate": "1877-01-01",
      "isQuoted": false,
      "vatNumber": "01654010345",
      "fiscalCode": "01654010345",
      "naceCode": "10.73",
      "naceSection": "C",
      "address": {
        "line1": "Via Mantova 166",
        "line2": null,
        "locality": "Parma",
        "postalCode": "43122",
        "countryCode": "IT"
      }
    },
    "latest": {
      "year": 2023,
      "isForecasted": false,
      "size": "L",
      "statementDate": "2023-12-31",
      "employees": 8760,
      "employeesYoY": 0.03
    },
    "peerCount": 2,
    "peers": [
      {
        "id": "Zm86SVRfMDExMjM0NTY3ODlfVToy",
        "identity": {
          "legalName": "PASTIFICIO ESEMPIO S.P.A.",
          "legalForm": "S.p.A.",
          "foundingYear": 1952,
          "incorporationDate": "1952-05-01",
          "isQuoted": false,
          "vatNumber": "01123456789",
          "fiscalCode": "01123456789",
          "naceCode": "10.73",
          "naceSection": "C",
          "address": null
        },
        "latest": {
          "year": 2023,
          "isForecasted": false,
          "size": "L",
          "statementDate": "2023-12-31",
          "employees": 3200,
          "employeesYoY": 0.01
        }
      }
    ]
  },
  "meta": {
    "requestId": "req_018f9c2e7b7a7c3e9a1b2c3d4e5f6a7b",
    "endpoint": "company-profile",
    "usage": { "quantity": 8, "unit": "credits" }
  }
}
```


# Company report
Source: https://docs.syrto.ai/api/endpoints/company-report

A comprehensive company report with multi-year financial statements, branches, and beneficial owners.

Returns the most comprehensive report for one company: everything in the [credit report](/api/endpoints/company-credit-report) plus multi-year financial statements (every reported line item), branches, and beneficial owners and subsidiaries. Ownership and officers carry names only.

<Info>
  Example endpoint. Whether it is part of your API depends on your organization's configuration - check [your schema](/api/openapi) for the endpoints provisioned for you.
</Info>

```
GET /companies/{fiscalCode}/report
```

## Path parameters

<ParamField type="string">
  The company's Italian fiscal code - either an 11-digit tax/VAT code or a 16-character codice fiscale. Case-insensitive.
</ParamField>

## Usage

Each successful call records a default measure of **1 call** (billed per call rather than by credits). The exact measure billed is always returned in `meta.usage` and may differ under your plan.

## Response

The `data` object contains:

<ResponseField name="isConsolidated" type="boolean">Whether the figures come from consolidated financial statements.</ResponseField>
<ResponseField name="latestFiledYear" type="number | null">The most recent fiscal year with filed figures.</ResponseField>

<ResponseField name="identity" type="CompanyIdentity">
  Descriptive company information (see [CompanyIdentity](/api/objects#companyidentity)), plus:

  * `activityStartDate` (`string | null`) - when the company started trading.
  * `dissolutionYear` (`number | null`) - the year of dissolution, if any.
  * `foreignOwned` (`boolean | null`) - whether the company is foreign-owned.
  * `controllingEntity` (`string | null`) - the controlling entity, if any.
</ResponseField>

<ResponseField name="registry" type="object | null">
  Registry contacts, or `null`: `pec`, `cciaa`, `rea` (each `string | null`).
</ResponseField>

<ResponseField name="headcount" type="object | null">
  `null`, or `{ employees: number, asOf: string }`.
</ResponseField>

<ResponseField name="risk" type="RiskIndicators">Risk flags. See [RiskIndicators](/api/objects#riskindicators).</ResponseField>

<ResponseField name="stateAids" type="object | null">
  State aid totals, or `null`. Fields `count`, `countLast36Months`, `amount`, `amountLast36Months` (each `number | null`).
</ResponseField>

<ResponseField name="ownership" type="object">
  Ownership across three lists, each an array of `{ name: string | null, share: number | null }`:

  * `shareholders`
  * `beneficialOwners`
  * `subsidiaries`
</ResponseField>

<ResponseField name="officers" type="object[]">
  Officers, each `{ name: string | null, role: string | null, roleCategory: string }`.
</ResponseField>

<ResponseField name="branches" type="CompanyBranch[]">Branch offices. See [CompanyBranch](/api/objects#companybranch).</ResponseField>
<ResponseField name="latest" type="AnnualSnapshot | null">The latest year of headline figures. See [AnnualSnapshot](/api/objects#annualsnapshot).</ResponseField>

<ResponseField name="financials" type="object[]">
  Recent years of financial statements, newest first. Each is an [AnnualSnapshot](/api/objects#annualsnapshot) extended with `metrics` - an array of [FinancialMetric](/api/objects#financialmetric) covering every reported line item for that year.
</ResponseField>

## Example

```bash theme={null}
curl -H "Authorization: Bearer $SYRTO_API_KEY" \
  https://api.syrto.ai/companies/01654010345/report
```

```json theme={null}
{
  "data": {
    "isConsolidated": false,
    "latestFiledYear": 2023,
    "identity": {
      "legalName": "BARILLA G. E R. FRATELLI - SOCIETÀ PER AZIONI",
      "legalForm": "S.p.A.",
      "foundingYear": 1877,
      "incorporationDate": "1877-01-01",
      "isQuoted": false,
      "vatNumber": "01654010345",
      "fiscalCode": "01654010345",
      "naceCode": "10.73",
      "naceSection": "C",
      "address": {
        "line1": "Via Mantova 166",
        "line2": null,
        "locality": "Parma",
        "postalCode": "43122",
        "countryCode": "IT"
      },
      "activityStartDate": "1877-01-01",
      "dissolutionYear": null,
      "foreignOwned": false,
      "controllingEntity": null
    },
    "registry": { "pec": "barilla@pec.example.it", "cciaa": "PR-123456", "rea": "PR-123456" },
    "headcount": { "employees": 8760, "asOf": "2023-12-31" },
    "risk": {
      "protestsOfBill": false,
      "insolvencyProceedings": false,
      "insolvencyApplications": false,
      "assetEncumbrances": false,
      "officersWithRiskIndicators": false
    },
    "stateAids": { "count": 12, "countLast36Months": 3, "amount": 1450000, "amountLast36Months": 320000 },
    "ownership": {
      "shareholders": [ { "name": "Barilla Holding S.p.A.", "share": 0.85 } ],
      "beneficialOwners": [ { "name": "Guido Barilla", "share": 0.28 } ],
      "subsidiaries": [ { "name": "Barilla France S.A.S.", "share": 1.0 } ]
    },
    "officers": [
      { "name": "Guido Barilla", "role": "Chairman", "roleCategory": "board" }
    ],
    "branches": [
      {
        "legalName": "BARILLA G. E R. FRATELLI - SEDE DI PEDRIGNANO",
        "address": { "line1": "Via Emilia", "line2": null, "locality": "Parma", "postalCode": "43122", "countryCode": "IT" }
      }
    ],
    "latest": {
      "year": 2023,
      "isForecasted": false,
      "size": "L",
      "statementDate": "2023-12-31",
      "employees": 8760,
      "employeesYoY": 0.03
    },
    "financials": [
      {
        "year": 2023,
        "isForecasted": false,
        "size": "L",
        "statementDate": "2023-12-31",
        "employees": 8760,
        "employeesYoY": 0.03,
        "metrics": [
          {
            "slug": "revenues_from_sales_and_services",
            "name": "Revenues from sales and services",
            "categories": ["income_statement"],
            "unit": "EUR",
            "value": 4200000000,
            "previousValue": 3900000000,
            "yoyChange": 0.077,
            "marketValue": null,
            "score": null
          }
        ]
      }
    ]
  },
  "meta": {
    "requestId": "req_018f9c2e7b7a7c3e9a1b2c3d4e5f6a7b",
    "endpoint": "company-report",
    "usage": { "quantity": 1, "unit": "calls" }
  }
}
```


# Errors
Source: https://docs.syrto.ai/api/errors

Error response shape and the full list of error codes returned by the Syrto API.

When a request fails, the API returns a non-`2xx` HTTP status and a JSON body with a single `error` object. The `code` is a stable, machine-readable identifier; branch on it rather than on the human-readable `message`.

## Error envelope

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "No company matches that identifier.",
    "requestId": "req_018f9c2e7b7a7c3e9a1b2c3d4e5f6a7b",
    "details": [
      { "path": "path.taxId", "message": "Required" }
    ]
  }
}
```

<ResponseField name="error.code" type="string">
  A stable error code from the table below. The set of possible codes is also enumerated in your [OpenAPI spec](/api/openapi).
</ResponseField>

<ResponseField name="error.message" type="string">
  A human-readable description. May change between releases - do not match on it programmatically.
</ResponseField>

<ResponseField name="error.requestId" type="string">
  The request id, matching the `X-Request-Id` header. Quote it in support requests.
</ResponseField>

<ResponseField name="error.details" type="object[]">
  Present only for validation failures (`invalid_params`). Each entry has a `path` (prefixed `path.`, `query.`, or `body.` to show where the invalid value was) and a `message`.
</ResponseField>

## Error codes

| Code                      | HTTP  | Meaning                                                                    |
| ------------------------- | ----- | -------------------------------------------------------------------------- |
| `missing_api_key`         | `401` | No bearer token in the `Authorization` header.                             |
| `invalid_api_key`         | `401` | The API key is not recognised.                                             |
| `credits_exhausted`       | `402` | Your credit balance is used up.                                            |
| `limit_reached`           | `402` | Your usage allowance for the current period is reached.                    |
| `client_not_configured`   | `403` | The key is valid but its organization has no API access configured.        |
| `not_entitled`            | `403` | Your plan does not include this endpoint.                                  |
| `unknown_endpoint`        | `404` | No such route.                                                             |
| `not_found`               | `404` | The request was valid but no company matches the identifier. Not billed.   |
| `invalid_params`          | `422` | A path or query parameter failed validation. See `details`.                |
| `rate_limited`            | `429` | You exceeded your [rate limit](/api/rate-limits). See `Retry-After`.       |
| `internal_error`          | `500` | An unexpected error occurred.                                              |
| `upstream_error`          | `502` | The upstream data source returned an error.                                |
| `auth_unavailable`        | `503` | Key validation is temporarily unavailable. Retry after a short wait.       |
| `entitlement_unavailable` | `503` | Entitlement checking is temporarily unavailable. Retry after a short wait. |
| `upstream_timeout`        | `504` | The upstream data source did not respond in time.                          |

<Note>
  A `not_found` (no matching company) is never billed. Neither is any request that fails before it reaches the data source - including validation, rate-limit, and entitlement errors.
</Note>

## Retrying

`429` and the `5xx` service-availability codes (`auth_unavailable`, `entitlement_unavailable`, `upstream_timeout`, and transient `upstream_error`) are safe to retry. When a `Retry-After` header is present, wait at least that many seconds; otherwise use exponential backoff. `4xx` codes other than `429` indicate a problem with the request or plan and won't succeed on retry.


# Introduction
Source: https://docs.syrto.ai/api/introduction

A custom, per-client REST API for Syrto's financial data on Italian companies.

<Info>
  The Syrto API is a bespoke, per-client offering. Syrto provisions a dedicated API for an organization on request, for specific use cases - it is not a self-serve public product. This section applies only if Syrto has set up an API for your organization. To request one, contact sales.
</Info>

The Syrto API is a REST layer over Syrto's financial database. Each organization gets its own API, tailored to its use case: the available endpoints, their pricing, and their response shapes are configured per client. Your own [OpenAPI schema](/api/openapi) - fetched with your API key - is the authoritative reference for exactly what your API exposes.

The pages in this section document the conventions shared by every Syrto API (authentication, the response envelope, errors, rate limits, versioning) and walk through example endpoints that illustrate the kind of resources Syrto can provision.

## Base URL

```
https://api.syrto.ai
```

All endpoints are served over HTTPS. Your API key determines which organization's API you reach and which endpoints you can call - see [Authentication](/api/authentication).

## Your endpoints

Because endpoints are configured per client, there is no single fixed list. The endpoints provisioned for your organization are described in [your own schema](/api/openapi), which you can fetch and preview with your API key.

The [example endpoints](/api/endpoints/company-financials) below show the kind of resources Syrto commonly exposes - your API may include some, all, or bespoke variants of them:

<CardGroup>
  <Card title="Company financials" icon="chart-line" href="/api/endpoints/company-financials">
    A financial snapshot for a single company by tax ID.
  </Card>

  <Card title="Credit report" icon="file-shield" href="/api/endpoints/company-credit-report">
    A full credit report - identity, risk indicators, ownership, officers, and recent financials.
  </Card>

  <Card title="Company profile" icon="building" href="/api/endpoints/company-profile">
    A company profile that adapts to size: peers for large companies, a deeper risk view for smaller ones.
  </Card>

  <Card title="Company report" icon="file-invoice" href="/api/endpoints/company-report">
    A comprehensive report with multi-year financial statements, branches, and beneficial owners.
  </Card>
</CardGroup>

## Response envelope

Every successful response is a JSON object with two top-level fields: `data` and `meta`.

```json theme={null}
{
  "data": { "...": "endpoint-specific resource" },
  "meta": {
    "requestId": "req_018f9c2e7b7a7c3e9a1b2c3d4e5f6a7b",
    "endpoint": "company-financials",
    "usage": { "quantity": 5, "unit": "credits" }
  }
}
```

<ResponseField name="data" type="object">
  The endpoint's resource. On a `200` response `data` is always present and non-null - a request that matches no company returns [`404 not_found`](/api/errors) instead, never a `200` with an empty body.
</ResponseField>

<ResponseField name="meta" type="object">
  Metadata about the call:

  * `requestId` - a unique id for the request (`req_` followed by a UUID). Quote it in support requests.
  * `endpoint` - the endpoint slug that served the request.
  * `usage` - the usage measure recorded for the call, as `{ quantity, unit }`.
</ResponseField>

## Response headers

Alongside the JSON body, responses carry a few headers:

| Header                                                              | On                        | Description                                         |
| ------------------------------------------------------------------- | ------------------------- | --------------------------------------------------- |
| `X-Request-Id`                                                      | every response            | The request id, matching `meta.requestId`.          |
| `X-Syrto-Endpoint`                                                  | success                   | The endpoint slug that served the request.          |
| `X-Usage-Quantity`                                                  | success                   | The usage quantity recorded for the call.           |
| `X-Usage-Unit`                                                      | success                   | The usage unit (e.g. `credits` or `calls`).         |
| `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` | every call to an endpoint | Your current [rate-limit](/api/rate-limits) budget. |
| `Retry-After`                                                       | `429` / `503`             | Seconds to wait before retrying, when applicable.   |

## Quickstart

Once Syrto has provisioned your API and you have a key, call one of your endpoints (the exact path depends on your schema):

```bash theme={null}
curl -H "Authorization: Bearer $SYRTO_API_KEY" \
  https://api.syrto.ai/companies/01654010345/financials
```

A successful call returns `200` with a `{ data, meta }` body. If the key is missing or invalid you get `401`; if no company matches, `404`. See [Errors](/api/errors) for the full list.

## Support

* **Email:** [support@syrto.ai](mailto:support@syrto.ai)
* **Website:** [syrto.ai](https://www.syrto.ai)


# Response objects
Source: https://docs.syrto.ai/api/objects

Shared object types that appear in the data of multiple Syrto API endpoints.

Several object types are reused across endpoints. They're documented once here; each endpoint page links back to the ones it uses. Fields typed `… | null` are always present but may be `null` when the value is unknown.

## CompanyIdentity

Descriptive, non-financial information about a company.

<ResponseField name="legalName" type="string | null">The official registered company name.</ResponseField>
<ResponseField name="legalForm" type="string | null">The legal form (e.g. S.p.A., S.r.l.).</ResponseField>
<ResponseField name="foundingYear" type="number | null">Year the company was founded.</ResponseField>
<ResponseField name="incorporationDate" type="string | null">Incorporation date.</ResponseField>
<ResponseField name="isQuoted" type="boolean | null">Whether the company is listed on a stock exchange.</ResponseField>
<ResponseField name="vatNumber" type="string | null">Italian VAT number (partita IVA).</ResponseField>
<ResponseField name="fiscalCode" type="string | null">Italian fiscal code (codice fiscale).</ResponseField>
<ResponseField name="naceCode" type="string | null">NACE economic activity code.</ResponseField>
<ResponseField name="naceSection" type="string | null">NACE section (the top-level letter).</ResponseField>
<ResponseField name="address" type="Address | null">Registered address. See [Address](#address).</ResponseField>

Some endpoints extend `CompanyIdentity` with extra fields (for example `foreignOwned`, `controllingEntity`, `activityStartDate`, `dissolutionYear`); those additions are noted on the relevant endpoint page.

## Address

<ResponseField name="line1" type="string | null">First address line.</ResponseField>
<ResponseField name="line2" type="string | null">Second address line.</ResponseField>
<ResponseField name="locality" type="string | null">City or town.</ResponseField>
<ResponseField name="postalCode" type="string | null">Postal code (CAP).</ResponseField>
<ResponseField name="countryCode" type="string">ISO 3166-1 alpha-2 country code.</ResponseField>

## AnnualSnapshot

A single fiscal year of headline figures.

<ResponseField name="year" type="number">The fiscal year.</ResponseField>
<ResponseField name="isForecasted" type="boolean">Whether the figures are forecast rather than reported.</ResponseField>
<ResponseField name="size" type="string | null">Company size band (e.g. `XS`, `S`, `M`, `L`).</ResponseField>
<ResponseField name="statementDate" type="string | null">Date of the financial statement.</ResponseField>
<ResponseField name="employees" type="number | null">Employee count for the year.</ResponseField>
<ResponseField name="employeesYoY" type="number | null">Year-over-year change in employee count.</ResponseField>

## RiskIndicators

Boolean flags summarising risk. Each is `true`, `false`, or `null` when unknown.

<ResponseField name="protestsOfBill" type="boolean | null">Protested bills on record.</ResponseField>
<ResponseField name="insolvencyProceedings" type="boolean | null">Active insolvency proceedings.</ResponseField>
<ResponseField name="insolvencyApplications" type="boolean | null">Insolvency applications filed.</ResponseField>
<ResponseField name="assetEncumbrances" type="boolean | null">Encumbrances on company assets.</ResponseField>
<ResponseField name="officersWithRiskIndicators" type="boolean | null">Officers carrying their own risk indicators.</ResponseField>

## FinancialMetric

A single financial statement line item or metric.

<ResponseField name="slug" type="string">Stable metric identifier.</ResponseField>
<ResponseField name="name" type="string">Human-readable metric name.</ResponseField>
<ResponseField name="categories" type="string[]">Categories the metric belongs to.</ResponseField>
<ResponseField name="unit" type="string | null">Unit of measure.</ResponseField>
<ResponseField name="value" type="number">The metric value for the year.</ResponseField>
<ResponseField name="previousValue" type="number | null">The value for the previous year.</ResponseField>
<ResponseField name="yoyChange" type="number | null">Year-over-year change.</ResponseField>
<ResponseField name="marketValue" type="number | null">A reference market value for the metric, where available.</ResponseField>
<ResponseField name="score" type="number | null">Syrto score for the metric, where available.</ResponseField>

## CompanyBranch

<ResponseField name="legalName" type="string">The branch's registered name.</ResponseField>
<ResponseField name="address" type="Address | null">The branch address. See [Address](#address).</ResponseField>


# Your API schema
Source: https://docs.syrto.ai/api/openapi

Fetch and preview your organization's OpenAPI schema with your API key, and generate a typed client.

Because the Syrto API is configured per client, your OpenAPI schema is the authoritative reference for your API - it lists exactly the endpoints, parameters, and response shapes provisioned for your organization. It is generated per API key and scoped to what that key can call, so it is the fastest way to see what your API actually exposes.

<Tip>
  Want to see what a schema looks like first? Browse the [interactive reference](/api/reference/overview) for the example endpoints - it renders the same way your own schema will.
</Tip>

## Preview your schema

Your schema is served as OpenAPI 3.1, in JSON or YAML. Both endpoints require your API key and are never billed. Create a key in the [Syrto dashboard](https://dashboard.syrto.ai/api-keys) (admins only), then fetch and save it:

```bash theme={null}
# JSON
curl -s https://api.syrto.ai/openapi.json \
  -H "Authorization: Bearer $SYRTO_API_KEY" -o syrto-openapi.json

# YAML
curl -s https://api.syrto.ai/openapi.yaml \
  -H "Authorization: Bearer $SYRTO_API_KEY" -o syrto-openapi.yaml
```

Then open the saved file in any OpenAPI viewer to browse it interactively. A good open-source choice is the [Swagger Editor](https://editor.swagger.io), which renders the file in your browser - the schema describes your API but never contains your key. Other options: [Scalar](https://github.com/scalar/scalar) (`npx @scalar/cli`), Postman, or an OpenAPI IDE plugin.

<Note>
  There is no browse-in-the-page schema viewer, by design: the schema is gated by your secret API key. Fetch it with your key and render it in a tool you control, rather than pasting the key into a web page.
</Note>

## Generate a client

The schema is a language-agnostic contract, so you can generate a typed client from the saved file with any OpenAPI generator:

```bash theme={null}
npx openapi-typescript syrto-openapi.json -o syrto.d.ts
```

Every operation carries a stable `operationId` (the endpoint slug), so generated method names stay clean, and the error `code` is a typed enum covering the full [error taxonomy](/api/errors) - a generated client sees exact codes, not a bare string.

## Versioning

Versioning is per-resource and appears in the resource name, only when a change would break existing callers:

* The first version of an endpoint uses the clean resource name - for example `/companies/{taxId}/financials`.
* A breaking change ships as a **new** endpoint with a `-vN` suffix (for example `/companies/{taxId}/financials-v2`). The original keeps working and is marked `deprecated` in the schema.
* There is no global `/v1` prefix - each endpoint evolves independently, and each version is a distinct operation with its own schema.

This means an existing integration never breaks silently: a new major version is a new URL you opt into, and the old one keeps serving until you migrate.


# Rate limits
Source: https://docs.syrto.ai/api/rate-limits

How the Syrto API rate-limits requests, and the headers that report your budget.

Requests are rate-limited per minute. The limit applies to each endpoint independently and is set by your plan.

## Rate-limit headers

Every call to an endpoint returns your current budget:

| Header                  | Description                                         |
| ----------------------- | --------------------------------------------------- |
| `X-RateLimit-Limit`     | Your maximum requests per minute for this endpoint. |
| `X-RateLimit-Remaining` | Requests left in the current window.                |
| `X-RateLimit-Reset`     | Seconds until the budget is fully replenished.      |

The limit refills continuously rather than resetting on a fixed boundary, so `X-RateLimit-Remaining` recovers gradually between calls.

## When you exceed the limit

A request over the limit returns [`429 rate_limited`](/api/errors) with a `Retry-After` header giving the number of seconds to wait:

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded.",
    "requestId": "req_018f9c2e7b7a7c3e9a1b2c3d4e5f6a7b"
  }
}
```

Rate limiting is applied before any billing check, so a throttled request is never billed. Wait for the `Retry-After` interval, then retry.

<Tip>
  Read `X-RateLimit-Remaining` from your responses and slow down as it approaches zero, rather than waiting for a `429`.
</Tip>


# Credit report
Source: https://docs.syrto.ai/api/reference/company-credit-report

api-reference/openapi.json GET /companies/{fiscalCode}/credit-report
A full credit report: identity and registry data, risk indicators, headcount, state aids, ownership and officers, and several recent years of headline financials. Ownership and officers carry names only.



# Company financials
Source: https://docs.syrto.ai/api/reference/company-financials

api-reference/openapi.json GET /companies/{taxId}/financials
A financial snapshot for a single company: identity, whether its figures are consolidated, and its latest reported year of headline figures.



# Company profile
Source: https://docs.syrto.ai/api/reference/company-profile

api-reference/openapi.json GET /companies/{taxId}/profile
A profile that adapts to company size: large companies come with a peer comparison, smaller companies with a deeper risk view. Exactly one of the two branches is present.



# Company report
Source: https://docs.syrto.ai/api/reference/company-report

api-reference/openapi.json GET /companies/{fiscalCode}/report
The most comprehensive report: everything in the credit report plus multi-year financial statements (every reported line item), branches, and beneficial owners and subsidiaries. Billed per call by default.



# Overview
Source: https://docs.syrto.ai/api/reference/overview

An interactive, in-page reference for the example endpoints, generated from a sample OpenAPI spec.

The pages in this section render the [example endpoints](/api/endpoints/company-financials) interactively from a sample OpenAPI spec, so you can browse parameters, response schemas, and examples in place.

<Info>
  This is a **sample** for browsing only - no API key is involved and no live requests are made. The endpoints, pricing, and shapes provisioned for your organization may differ. To explore your own API, fetch [your schema](/api/openapi) with your API key and render it in a viewer you control.
</Info>

Use the navigation to open each endpoint:

* [Company financials](/api/reference/company-financials)
* [Credit report](/api/reference/company-credit-report)
* [Company profile](/api/reference/company-profile)
* [Company report](/api/reference/company-report)


# Syrto documentation
Source: https://docs.syrto.ai/index

Financial intelligence for Italian companies, accessible directly from your AI assistant or over REST.

Syrto gives you structured financial data on Italian companies. Bring Syrto's analysis tools into your AI assistant with the [MCP server](/mcp/introduction), or, for provisioned clients, call the data directly from your own systems with a custom [REST API](/api/introduction).

## MCP server

Use Syrto's analysis tools directly in Claude, Cursor, Windsurf, or any MCP-compatible AI client.

<CardGroup>
  <Card title="Introduction" icon="book-open" href="/mcp/introduction">
    Learn what the Syrto MCP server does and how it works.
  </Card>

  <Card title="Setup" icon="plug" href="/mcp/setup">
    Connect the Syrto MCP server to your AI client.
  </Card>

  <Card title="Find a company" icon="magnifying-glass" href="/mcp/tools/find-company">
    Look up any Italian company by name or tax ID.
  </Card>

  <Card title="Financial metrics" icon="chart-line" href="/mcp/tools/company-metrics">
    Retrieve metrics, radar scores, and multi-year trends.
  </Card>
</CardGroup>

## REST API

A custom, per-client REST API over Syrto's data, provisioned on request for specific use cases.

<CardGroup>
  <Card title="Introduction" icon="book-open" href="/api/introduction">
    Learn how the Syrto REST API is structured.
  </Card>

  <Card title="Authentication" icon="key" href="/api/authentication">
    Authenticate with a bearer API key.
  </Card>

  <Card title="Your API schema" icon="code" href="/api/openapi">
    Fetch and preview your own schema with your API key.
  </Card>

  <Card title="Example endpoints" icon="server" href="/api/endpoints/company-financials">
    Financials, credit reports, profiles, and full company reports.
  </Card>
</CardGroup>


# Introduction
Source: https://docs.syrto.ai/mcp/introduction

Use Syrto financial data directly in your AI assistant via the Model Context Protocol.

The Syrto MCP server connects your AI assistant to Syrto's financial database, letting you analyze Italian companies without leaving your conversation. Ask natural language questions and get structured financial data in response.

## What you can do

<CardGroup>
  <Card title="Look up companies" icon="magnifying-glass">
    Find any Italian company by name or tax ID (codice fiscale) and get its company ID for further analysis.
  </Card>

  <Card title="Financial analysis" icon="chart-line">
    Get a full financial assessment across profitability, liquidity, solvency, and structure - with radar scores in a single call.
  </Card>

  <Card title="Ownership and structure" icon="sitemap">
    See who owns and controls a company - officers, shareholders, beneficial owners, subsidiaries, and listed status.
  </Card>

  <Card title="Spider graphs" icon="chart-radar">
    Explore thematic breakdowns across axes like operational profitability, autonomy, and reliability.
  </Card>

  <Card title="Financial statements" icon="file-invoice">
    Generate filled income statements and balance sheets using Syrto's financial statement templates.
  </Card>

  <Card title="Metric definitions" icon="book">
    Look up how any metric is defined, calculated, and what drives it.
  </Card>

  <Card title="Search companies" icon="filter">
    Find companies by sector, region, size, financial metrics, or natural language description.
  </Card>

  <Card title="Market statistics" icon="chart-bar">
    Get aggregate statistics - count, average, median - across company segments for benchmarking.
  </Card>
</CardGroup>

## Examples

### In-depth performance analysis with competitor comparison

> "Analyse the performance of Vetreria Etrusca over the last 3 years. Identify 3 strengths and 3 weaknesses, then compare it against its 3 main competitors."

Retrieves multi-year financial data, highlights key strengths and weaknesses, and produces a side-by-side competitor comparison - all in a single conversation.

### Ownership and control

> "Who owns Barilla and who runs it?"

Returns Barilla's shareholders, officers, and beneficial owners, with ownership percentages and roles.

### Search companies by criteria

> "Find large food companies in Emilia-Romagna with revenue above 100 million"

Returns a list of companies matching the sector, region, and financial filters - each with a `company_id` you can use for deeper analysis.

## Get started

You need a free Syrto account to use the MCP server. [Sign up at syrto.ai](https://syrto.ai). A free tier is available; full access requires a paid plan.

<Card title="Set up the MCP server" icon="plug" href="/mcp/setup">
  Connect Syrto to Claude, ChatGPT, Microsoft 365 Copilot, or any MCP client.
</Card>

***

## Privacy policy

See our privacy policy at [syrto.ai/privacy](https://www.syrto.ai/privacy).

## Support

* **Email:** [support@syrto.ai](mailto:support@syrto.ai)
* **Website:** [syrto.ai](https://www.syrto.ai)


# Setup
Source: https://docs.syrto.ai/mcp/setup

Connect the Syrto MCP server to your AI assistant.

## Prerequisites

Create a free Syrto account at [syrto.ai](https://syrto.ai) before connecting. No API key is needed - authentication is handled via OAuth when you install the connector.

<Info>
  A free tier is available. Full access to all tools and data requires a paid plan.
</Info>

***

## Claude

<Info>
  **Planned.** A pre-packaged Syrto connector for the claude.ai marketplace is on the roadmap. In the meantime, connect via [Any MCP client](#any-mcp-client) below.
</Info>

***

## Microsoft 365 Copilot

<Info>
  **Coming soon.** Syrto will be available as an app in the Microsoft 365 app store.
</Info>

***

## ChatGPT

<Info>
  **Planned.** A Syrto app for the ChatGPT GPT store is on the roadmap. In the meantime, connect via [Any MCP client](#any-mcp-client) below.
</Info>

***

## Any MCP client

For any MCP-compatible client, point it at the Syrto HTTP MCP server:

```
https://mcp.syrto.ai/mcp
```

OAuth authentication is handled automatically by your client's MCP auth flow on first connection - just add the URL and follow the login prompt when it appears.

***

## Verify the connection

Once connected in any client, try this prompt:

```
Analyse the performance of Vetreria Etrusca over the last 3 years.
Identify 3 strengths and 3 weaknesses, then compare it against its 3 main competitors.
```

If everything is working, you'll get a multi-year financial analysis with strengths, weaknesses, and a competitor comparison.

***

## Rate limits

The Syrto MCP server enforces the following rate limits per account:

| Limit           | Window   |
| --------------- | -------- |
| 60 requests     | 1 minute |
| 1,000 requests  | 1 hour   |
| 10,000 requests | 1 day    |

All limits apply concurrently - a request is rejected if any limit is exceeded.


# Aggregate companies
Source: https://docs.syrto.ai/mcp/tools/aggregate-companies

Get aggregated financial statistics - count, average, median, min, max - for companies matching sector, region, size, and metric filters.

`syrto_aggregate_companies` returns statistical summaries (count, average, median, min, max) for companies matching your filters. Use it to understand market segments - e.g. "average revenue of medium manufacturing companies in Veneto" or "how many large companies are in sector C".

<Tip>
  This tool returns **aggregate statistics**, not individual company data. To find specific companies matching the same filters, use [`syrto_search_companies`](/mcp/tools/search-companies).
</Tip>

## Use this tool to

* Count companies matching a set of criteria
* Get average, median, or range statistics for a metric across a segment
* Benchmark a company against its market segment

## Arguments

<ParamField type="integer">
  Fiscal year to aggregate.
</ParamField>

<ParamField type="string (JSON array)">
  JSON array of 1–10 metric slugs to compute statistics for. Use [`syrto_search_metric_definitions`](/mcp/tools/metric-definitions) or [`syrto_list_available_metrics`](/mcp/tools/list-available-metrics) to find valid slugs.

  **Example:** `'["revenues_from_sales_and_services", "ebitda"]'`
</ParamField>

<ParamField type="string (JSON object)">
  Company profile filters as a JSON object. All fields are optional:

  | Field                                      | Type   | Description                                                                                                                            |
  | ------------------------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
  | `nace`                                     | string | EU NACE sector code. Auto-detects level: section letter (`A`–`U`), division (2 digits), group (e.g. `"10.1"`), class (e.g. `"10.11"`). |
  | `nuts`                                     | string | EU NUTS region code. Auto-detects level: level 1 (3 chars), level 2 (4 chars), level 3 (5 chars).                                      |
  | `semantic_search`                          | string | Natural language description to search company profiles (max 500 characters).                                                          |
  | `age`                                      | object | Company age filter with `min` and/or `max` in years.                                                                                   |
  | `shareholder_age`                          | object | Average age of shareholders with `min` and/or `max` in years.                                                                          |
  | `beneficial_owner_age`                     | object | Average age of beneficial owners with `min` and/or `max` in years.                                                                     |
  | `executive_officer_age`                    | object | Average age of executive officers (CEOs, managing directors) with `min` and/or `max` in years.                                         |
  | `representation_and_authority_officer_age` | object | Average age of officers with representation and signing authority, with `min` and/or `max` in years.                                   |
  | `target_market`                            | string | One of: `B2B`, `B2C`, `B2G`, `B2B2C`, `B2B2G`, `C2C`, `C2B`, `G2C`, `G2B`.                                                             |
  | `match_cutoff`                             | float  | Minimum semantic similarity score (0.0–1.0) when using `semantic_search`.                                                              |
  | `country_code`                             | string | ISO 3166-1 alpha-2 country code (e.g. `"IT"`).                                                                                         |

  **Example:** `'{"nace": "C", "nuts": "ITH5"}'`
</ParamField>

<ParamField type="string[]">
  One or more company size classifications: `"XS"`, `"S"`, `"M"`, `"L"` (e.g. `["S", "M"]`).
</ParamField>

<ParamField type="string (JSON array)">
  Up to 10 metric value filters to narrow the population. Each object has `slug` (required), `min` (optional), `max` (optional).

  **Example:** `'[{"slug": "revenues_from_sales_and_services", "min": 1000000}]'`
</ParamField>

<ParamField type="string (JSON object)">
  Employee count filter with `min` and/or `max`.

  **Example:** `'{"min": 50}'`
</ParamField>

<ParamField type="string (JSON object)">
  Aggregate over companies whose position on the Syrto Radar plane (0–100 on both axes) matches the filter. Combines via AND with all other filters. At least one of `size`, `efficiency`, or `polygon` is required.

  | Field        | Type   | Description                                                                                                                                                                                                                                      |
  | ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | `size`       | object | Inclusive range on the Radar size axis with `min` and/or `max` (0–100). Distinct from the top-level `size` parameter (XS/S/M/L band).                                                                                                            |
  | `efficiency` | object | Inclusive range on the Radar efficiency axis with `min` and/or `max` (0–100).                                                                                                                                                                    |
  | `polygon`    | object | Arbitrary polygon over the (size, efficiency) plane. Has a `vertices` list of 3–64 points, each `{ "size": 0–100, "efficiency": 0–100 }`. Use axis ranges for rectangles or strips; use the polygon for triangles, L-shapes, or concave regions. |

  **Example:** `'{"efficiency": {"min": 70}}'`
</ParamField>

<ParamField type="boolean">
  Filter by consolidated financial statements. Default: `false` (non-consolidated).
</ParamField>

<ParamField type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

## Returns

<ResponseField name="years" type="object[]">
  One entry per requested year, each containing:
</ResponseField>

<ResponseField name="years[].company_count" type="integer">
  Total number of companies matching the filters.
</ResponseField>

<ResponseField name="years[].employee_stats" type="object">
  Employee count statistics across matching companies:

  * `count` - number of companies with employee data
  * `average`, `median`, `minimum`, `maximum` - statistical summaries
</ResponseField>

<ResponseField name="years[].metric_stats" type="object[]">
  One entry per requested metric slug, each with:

  * `name` - human-readable metric name (use this for display, not `slug`)
  * `slug` - internal identifier
  * `stats.count` - number of companies with data for this metric
  * `stats.average`, `stats.median`, `stats.minimum`, `stats.maximum` - statistical summaries
</ResponseField>

<ResponseField name="years[].radar" type="object">
  Radar score statistics across matching companies:

  * `efficiency_avg`, `efficiency_median` - Efficiency score summaries (0–100)
  * `size_avg`, `size_median` - Size score summaries (0–100)
</ResponseField>

<ResponseField name="note" type="string">
  Context note about data availability and where to find more on syrto.ai.
</ResponseField>

<ResponseField name="source_url" type="string">
  Link to the Syrto web app, where you can explore more data and insights.
</ResponseField>

## Example

**Average revenue for large manufacturers in Emilia-Romagna:**

```json theme={null}
{
  "year": 2023,
  "anagraphic_filters": "{\"nace\": \"C\", \"nuts\": \"ITH5\"}",
  "size": "L",
  "aggregate_metric_slugs": "[\"revenues_from_sales_and_services\"]"
}
```

**Response (abbreviated):**

```json theme={null}
{
  "result": {
    "years": [
      {
        "year": 2023,
        "company_count": 3690,
        "employee_stats": {
          "count": 3045,
          "average": 333.15,
          "median": 201.0
        },
        "metric_stats": [
          {
            "name": "Revenues From Sales And Services",
            "slug": "revenues_from_sales_and_services",
            "stats": {
              "count": 3690,
              "average": 214504329.44,
              "median": 88501574.0
            }
          }
        ],
        "radar": {
          "efficiency_avg": 61.54,
          "efficiency_median": 68.25,
          "size_avg": 80.45,
          "size_median": 80.42
        }
      }
    ]
  },
  "note": "Syrto data summary. ...",
  "source_url": "https://app.syrto.ai"
}
```


# Company analysis
Source: https://docs.syrto.ai/mcp/tools/company-analysis

Get a full categorised financial analysis of a company - profitability, liquidity, solvency, and structure - with radar scores in a single call.

`syrto_get_company_analysis` is the primary tool for financial analysis. It returns all metrics that drive the Syrto radar scores, pre-grouped into four categories, plus radar positioning and explanations - in a single call.

<Tip>
  This is the best starting point for any financial assessment. Only reach for [`syrto_get_company_metrics`](/mcp/tools/company-metrics) when you need specific metrics not covered by the four categories below.
</Tip>

## Use this tool to

* Get a comprehensive financial assessment across profitability, liquidity, solvency, and structure
* See radar scores (efficiency and size) alongside the metrics that drive them
* Compare performance year-on-year

**Related tools:** For specific metrics outside the four categories, use [Company metrics](/mcp/tools/company-metrics). For thematic breakdowns, use [Spider graphs](/mcp/tools/spider-graphs). For qualitative profile data, use [Company overview](/mcp/tools/company-overview).

## Arguments

<ParamField type="string">
  The company ID from [`syrto_find_company`](/mcp/tools/find-company).
</ParamField>

<ParamField type="integer">
  Fiscal year to retrieve (e.g. `2022`). If omitted, returns the most recent year plus the prior year (controlled by `include_prior_year`).
</ParamField>

<ParamField type="boolean">
  When `true` (default), returns the most recent year plus the prior year for trend context. When `false`, returns only the most recent year. Ignored when `year` is provided.
</ParamField>

<ParamField type="boolean">
  If `true`, each metric includes a `market_value` field with the sector benchmark for comparison. Default: `false`.
</ParamField>

<ParamField type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

## Returns

A JSON object with `company_name`, `available_years`, and per-year data. Each year contains:

<ResponseField name="available_years" type="integer[]">
  All fiscal years with data for this company.
</ResponseField>

<ResponseField name="year" type="integer">
  Fiscal year.
</ResponseField>

<ResponseField name="size" type="string">
  EU SME classification for that year (e.g. "Large", "Medium").
</ResponseField>

<ResponseField name="employee_count" type="float | null">
  Headcount for that year. `null` if not available.
</ResponseField>

<ResponseField name="radar.efficiency" type="float | null">
  Efficiency score (0–100): how well the company converts resources into results. Higher is better.
</ResponseField>

<ResponseField name="radar.size" type="float | null">
  Size score (0–100): how large and stable the company is relative to its sector. Higher is better.
</ResponseField>

<ResponseField name="radar.trajectory_distance / trajectory_angle" type="float">
  Year-on-year movement in the radar space - magnitude and direction of change.
</ResponseField>

<ResponseField name="radar.explanation" type="object | null">
  Structured explanation of what drives the efficiency and size positioning. Contains two top-level keys:

  * `efficiency` - object with `movement` and `position`, each containing:
    * `value` - numeric score
    * `contributions` - list of items, each with `contribution` (float) and `category_slug` identifying the driver
  * `size` - same structure as `efficiency`, but contributions use `metric_slug` instead of `category_slug`
</ResponseField>

<ResponseField name="categories" type="object[]">
  The four Syrto financial categories, each with:

  * `name` - human-readable category name
  * `slug` - internal category identifier (e.g. `"profitability"`, `"liquidity"`)
  * `metrics` - list of metric objects, each with:
    * `name` - human-readable metric name
    * `slug` - internal metric identifier
    * `value` - numeric value (or `null` if unavailable)
    * `better_when` - object `{"when_type": "HIGHER"}`, `{"when_type": "LOWER"}`, `{"when_type": "NEAR_TARGET"}`, or `null`
    * `market_value` - sector benchmark (only when `include_market_data` is `true`)
</ResponseField>

<ResponseField name="note" type="string">
  Context note about data availability and where to find more on syrto.ai.
</ResponseField>

<ResponseField name="source_url" type="string">
  Link to the Syrto web app, where you can explore more data and insights.
</ResponseField>

### The four categories

| Category          | What it covers                                                 |
| ----------------- | -------------------------------------------------------------- |
| **Profitability** | Margins (EBITDA, EBIT), returns (ROE, ROA), revenue growth     |
| **Liquidity**     | Working capital, cash conversion cycle, short-term buffers     |
| **Solvency**      | Debt load, coverage ratios, leverage, financial sustainability |
| **Structure**     | Asset composition, capital structure, capex intensity          |

<Note>
  `null` metric values mean data is not available. The `slug` fields are internal identifiers - use the `name` fields for display.
</Note>

## Example

**Full financial analysis of Barilla:**

```json theme={null}
{
  "company_id": "Zm86SVRfMDE2NTQwMTAzNDVfVTox"
}
```

**Result:**

* Returns the most recent year plus the prior year by default (set `include_prior_year` to `false` for just the latest year)
* Includes all four categories with their metrics, radar scores (efficiency and size), and an explanation of what drives the positioning


# Company metrics
Source: https://docs.syrto.ai/mcp/tools/company-metrics

Retrieve specific financial metric values for a company by slug - use when you need metrics outside what syrto_get_company_analysis covers.

`syrto_get_company_metrics` retrieves individual metric values by slug for a company. Use it when you need specific metrics not already covered by [`syrto_get_company_analysis`](/mcp/tools/company-analysis) - for example, individual balance sheet line items, custom metric sets, or precise comparisons across companies.

<Tip>
  For general financial analysis, use [`syrto_get_company_analysis`](/mcp/tools/company-analysis) instead - it returns all four Syrto categories plus radar scores in a single call, with no slug discovery needed.

  To find metric slugs, use [`syrto_list_available_metrics`](/mcp/tools/list-available-metrics) or [`syrto_search_metric_definitions`](/mcp/tools/metric-definitions).
</Tip>

## Use this tool to

* Retrieve specific metrics not covered by the four Syrto categories (e.g. raw balance sheet items, niche ratios)
* Compare companies on a custom metric set
* Get metric values for a specific year or across multiple years

## Arguments

<ParamField type="string">
  The company ID from [`syrto_find_company`](/mcp/tools/find-company).
</ParamField>

<ParamField type="string[]">
  List of metric slugs to retrieve (e.g. `["total_assets", "net_financial_position"]`). If omitted, returns all available metrics. Use [`syrto_list_available_metrics`](/mcp/tools/list-available-metrics) to discover slugs.
</ParamField>

<ParamField type="integer">
  Fiscal year to retrieve (e.g. `2022`). If omitted, returns the most recent year only (controlled by `last_n_years`, which defaults to `1`). Takes precedence over `last_n_years`.
</ParamField>

<ParamField type="integer">
  Number of most recent years to return. Default `1` (most recent year only). Max `5`. Pass `null` to return all available years. Ignored when `year` is provided.
</ParamField>

<ParamField type="boolean">
  If `true`, each metric includes a `market_value` field with the sector benchmark for comparison. Default: `false`.
</ParamField>

<ParamField type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

<Warning>
  You cannot omit both `metric_slugs` and `year` - this would return all metrics across all years, exceeding response limits. Provide at least one.
</Warning>

## Returns

A JSON object with `company_name`, `available_years`, and per-year data. Each year contains:

<ResponseField name="available_years" type="integer[]">
  All fiscal years with data for this company.
</ResponseField>

<ResponseField name="year" type="integer">
  Fiscal year.
</ResponseField>

<ResponseField name="size" type="string">
  EU SME classification for that year.
</ResponseField>

<ResponseField name="employee_count" type="float | null">
  Headcount for that year.
</ResponseField>

<ResponseField name="metrics" type="object[]">
  List of metric objects, each with:

  * `name` - human-readable metric name
  * `slug` - internal identifier (use `name` for display)
  * `value` - numeric value (or `null` if unavailable)
  * `better_when` - object `{"when_type": "HIGHER"}`, `{"when_type": "LOWER"}`, `{"when_type": "NEAR_TARGET"}`, or `null`
  * `market_value` - sector benchmark (only when `include_market_data` is `true`)
</ResponseField>

<ResponseField name="radar.efficiency" type="float | null">
  Efficiency score (0–100): how well the company converts resources into results.
</ResponseField>

<ResponseField name="radar.size" type="float | null">
  Size score (0–100): how large and stable the company is relative to its sector.
</ResponseField>

<ResponseField name="radar.trajectory_distance / trajectory_angle" type="float">
  Year-on-year movement in the radar space.
</ResponseField>

<ResponseField name="note" type="string">
  Context note about data availability and where to find more on syrto.ai.
</ResponseField>

<ResponseField name="source_url" type="string">
  Link to the Syrto web app, where you can explore more data and insights.
</ResponseField>

## Example

**Get specific balance sheet metrics for Barilla:**

```json theme={null}
{
  "company_id": "Zm86SVRfMDE2NTQwMTAzNDVfVTox",
  "metric_slugs": ["total_assets", "net_financial_position"]
}
```

**Result:**

* Returns only the requested metrics for the most recent year by default
* Use `last_n_years` for trends, or `year` for a specific period
* Use [`syrto_list_available_metrics`](/mcp/tools/list-available-metrics) to discover available slugs


# Company overview
Source: https://docs.syrto.ai/mcp/tools/company-overview

Get a company's qualitative profile: sector, location, activity, and employee count.

`syrto_get_company_anagraphic` returns descriptive information about a company - what it does, where it's based, what sector it's in, and its size classification. It also includes contact details, social media profiles, and headcount breakdowns. It returns no financial figures.

**Related tools:** For financial data, use [Company analysis](/mcp/tools/company-analysis). For ownership structure, use [Company structure](/mcp/tools/company-structure).

## Use this tool to

* Learn what a company does, its sector, and location
* Get industry classification (ATECO/EU NACE), employee count, and website
* Find contact information, social media profiles, and VAT/tax details

## Arguments

<ParamField type="string">
  The company ID from [`syrto_find_company`](/mcp/tools/find-company).
</ParamField>

<ParamField type="integer">
  Year for size classification (e.g. `2023`). Defaults to the most recent available year.
</ParamField>

<ParamField type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

## Returns

<ResponseField name="company_name" type="string">
  Official legal name.
</ResponseField>

<ResponseField name="ateco_section / ateco_division / ateco_group / ateco_class" type="string">
  EU NACE sector codes at increasing levels of specificity.
</ResponseField>

<ResponseField name="activity_overview" type="string">
  Short description of the company's business.
</ResponseField>

<ResponseField name="target_markets" type="string[]">
  Geographic markets the company operates in.
</ResponseField>

<ResponseField name="target_markets_description" type="string | null">
  Free-text description of the company's target markets.
</ResponseField>

<ResponseField name="region / city / country_code" type="string">
  Company location.
</ResponseField>

<ResponseField name="lau" type="string | null">
  LAU (Local Administrative Unit) code - the municipality (comune). Pass it to the `lau` filter in [Search companies](/mcp/tools/search-companies) to find peers in the same municipality.
</ResponseField>

<ResponseField name="website_url" type="string">
  Company website.
</ResponseField>

<ResponseField name="size_classification" type="string">
  EU SME category (e.g. `MEDIUM`, `LARGE`).
</ResponseField>

<ResponseField name="employee_count" type="float">
  Most recent headcount from annual filings.
</ResponseField>

<ResponseField name="founding_year" type="integer | null">
  Year the company was founded.
</ResponseField>

<ResponseField name="incorporation_date" type="string | null">
  Formal incorporation date (ISO 8601).
</ResponseField>

<ResponseField name="activity_start_date" type="string | null">
  Date business activity began (ISO 8601).
</ResponseField>

<ResponseField name="tax_id" type="string | null">
  Taxpayer identification number (codice fiscale).
</ResponseField>

<ResponseField name="vat_number" type="string | null">
  EU VAT number.
</ResponseField>

<ResponseField name="contact_emails" type="object[]">
  Email addresses with tags. Each entry has:

  * `value` - email address
  * `tags` - list of labels (e.g. `SUPPORT`, `INFO`, `PRESS`, `SALES`)
</ResponseField>

<ResponseField name="contact_phones" type="object[]">
  Phone numbers with tags. Each entry has:

  * `value` - phone number
  * `tags` - list of labels (e.g. `INFO`, `CUSTOMER_SERVICE`, `PARTNERSHIPS`)
</ResponseField>

<ResponseField name="social_media_profiles" type="object[]">
  Social media links. Each entry has:

  * `platform` - platform name (e.g. `LINKEDIN`, `INSTAGRAM`, `X`, `YOUTUBE`, `FACEBOOK`)
  * `url` - profile URL
</ResponseField>

<ResponseField name="headcount_employees" type="object | null">
  Real-time employee headcount:

  * `value` - number of employees
  * `updated_at` - when the data was last refreshed (ISO 8601)
</ResponseField>

<ResponseField name="headcount_contractors" type="object | null">
  Real-time contractor/collaborator headcount:

  * `value` - number of contractors
  * `updated_at` - when the data was last refreshed (ISO 8601)
</ResponseField>

<ResponseField name="risk_indicators" type="object | null">
  Legal and registry risk flags. Each flag is `true` when the company has the relevant record on file, `false` when it does not, and `null` when unknown:

  * `has_protests_of_bill` - protested (unpaid) bills
  * `has_insolvency_proceedings` - insolvency proceedings under way
  * `has_insolvency_applications` - insolvency applications filed
  * `has_asset_encumbrances` - charges or liens on assets
</ResponseField>

<ResponseField name="has_officers_with_risk_indicators" type="boolean | null">
  Whether any of the company's officers carry their own risk indicators. `null` if unknown.
</ResponseField>

<ResponseField name="note" type="string">
  Context note about data availability and where to find more on syrto.ai.
</ResponseField>

<ResponseField name="source_url" type="string">
  Link to the Syrto web app, where you can explore more data and insights.
</ResponseField>

<ResponseField name="warning" type="string | null">
  Data availability warning (e.g. when the requested year is not available and the most recent year is returned instead).
</ResponseField>

## Example

**Get the profile of Barilla:**

```json theme={null}
{
  "company_id": "Zm86SVRfMDE2NTQwMTAzNDVfVTox"
}
```

**Response (abbreviated):**

```json theme={null}
{
  "result": {
    "company_name": "BARILLA G. E R. FRATELLI - SOCIETÀ PER AZIONI",
    "activity_overview": "Produces and markets pasta, sauces, and bakery products worldwide, handling manufacturing, distribution, and marketing.",
    "ateco_section": "C",
    "ateco_class": "10.73",
    "city": "PARMA",
    "region": "ITH5",
    "country_code": "IT",
    "size_classification": "L",
    "employee_count": 3928.0,
    "founding_year": 1988,
    "tax_id": "01654010345",
    "vat_number": "IT01654010345",
    "website_url": "https://www.barillagroup.com/",
    "contact_emails": [
      { "value": "mediarelations@barilla.com", "tags": ["PRESS"] }
    ],
    "social_media_profiles": [
      { "platform": "LINKEDIN", "url": "https://linkedin.com/company/barilla_group" }
    ],
    "headcount_employees": { "value": 3723, "updated_at": "2025-03-31 00:00:00+00:00" }
  },
  "note": "Syrto data summary. More metrics, benchmarks, and insights are available at https://www.syrto.ai",
  "source_url": "https://app.syrto.ai"
}
```


# Company structure
Source: https://docs.syrto.ai/mcp/tools/company-structure

Get the ownership and organisational structure of a company - officers, shareholders, beneficial owners, and subsidiaries.

`syrto_get_company_structure` returns the ownership and organisational structure of a company: who controls it, who owns shares in it, who runs it, and what entities sit below it.

**Related tools:** For company profile data (sector, location, employees), use [Company overview](/mcp/tools/company-overview). For financial metrics, use [Company analysis](/mcp/tools/company-analysis).

## Use this tool to

* Find out who owns or controls a company
* See officers, management, board members, and executives
* Explore subsidiaries and group structure
* Determine if a company is publicly listed or foreign-owned

## Arguments

<ParamField type="string">
  The company ID from [`syrto_find_company`](/mcp/tools/find-company).
</ParamField>

<ParamField type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

## Returns

<ResponseField name="company_name" type="string">
  Official legal name of the company.
</ResponseField>

<ResponseField name="legal_entity_type" type="string | null">
  Legal form of the entity, e.g. `"S.p.A."`, `"S.r.l."`. `null` if not available.
</ResponseField>

<ResponseField name="controlling_entity_category" type="string | null">
  Category of the controlling entity. Common values: `FAMILY`, `INDUSTRIAL_GROUP`, `FINANCIALLY_OWNED_GROUP`. `null` if not determined.
</ResponseField>

<ResponseField name="is_quoted" type="boolean | null">
  Whether the company is listed on a stock exchange. `null` if not available.
</ResponseField>

<ResponseField name="is_foreign_owned" type="boolean | null">
  Whether the company is majority foreign-owned. `null` if not available.
</ResponseField>

<ResponseField name="officers" type="object[]">
  Up to 15 officers. Each entry has:

  * `name` - officer name (`null` if not available)
  * `role_category` - standardised role category
  * `role` - specific role title
  * `age` - age in completed years (`null` for non-person entities or if unknown)
</ResponseField>

<ResponseField name="shareholders" type="object[]">
  Up to 10 direct shareholders. Each entry has:

  * `name` - shareholder name (`null` if not available)
  * `share_percent` - ownership percentage (`null` if not publicly disclosed)
  * `age` - age in completed years (`null` for corporate shareholders or if unknown)
</ResponseField>

<ResponseField name="beneficial_owners" type="object[]">
  Up to 10 beneficial owners (ultimate controlling persons). Each entry has:

  * `name` - beneficial owner name (`null` if not available)
  * `share_percent` - effective ownership percentage (`null` if not disclosed)
  * `age` - age in completed years (`null` if unknown)
</ResponseField>

<ResponseField name="subsidiaries" type="object[]">
  Up to 15 subsidiaries. Each entry has:

  * `name` - subsidiary name (`null` if not available)
  * `share_percent` - parent's ownership stake (`null` if not disclosed)
</ResponseField>

<ResponseField name="linked_companies" type="object[]">
  Up to 15 companies controlled by the same parent entity (share ≥ 51%). Each entry has:

  * `id` - company ID (can be passed to other Syrto tools)
  * `name` - company name (`null` if not available)
</ResponseField>

<ResponseField name="companies_with_shared_officers" type="object[]">
  Up to 15 companies that share one or more officers with this company. Each entry has:

  * `id` - company ID (can be passed to other Syrto tools)
  * `name` - company name (`null` if not available)
</ResponseField>

<ResponseField name="note" type="string">
  Context note about data availability and where to find more on syrto.ai.
</ResponseField>

<ResponseField name="source_url" type="string">
  Link to the Syrto web app, where you can explore more data and insights.
</ResponseField>

<Note>
  Results are capped: officers, subsidiaries, linked companies, and companies with shared officers (max 15 each); shareholders and beneficial owners (max 10 each). `share_percent` values may be `null` if not publicly disclosed.
</Note>

## Example

**Get the ownership structure of Ferrari:**

```json theme={null}
{
  "company_id": "company_ferrari_id"
}
```

**Result:**

* Shareholders with names and ownership percentages where disclosed
* `controlling_entity_category` and `is_quoted` for full ownership context
* Officers with names, role categories, and specific titles
* Subsidiaries with names and ownership stakes


# Compare companies
Source: https://docs.syrto.ai/mcp/tools/compare-companies

Compare specific financial metrics side-by-side across multiple companies.

`syrto_compare_companies` fetches the same metrics for multiple companies in a single call, returning results side-by-side. It is significantly faster than calling [`syrto_get_company_metrics`](/mcp/tools/company-metrics) once per company.

<Tip>
  Metric slugs must come from [`syrto_list_available_metrics`](/mcp/tools/list-available-metrics) or [`syrto_search_metric_definitions`](/mcp/tools/metric-definitions). Invalid slugs silently return no data.
</Tip>

## Use this tool to

* Compare specific financial KPIs across 2 or more companies side-by-side
* Check which company performs best on a given metric (e.g. ROE, EBITDA)
* Get year-on-year metric trends for multiple companies at once

Related tools: For single-company metrics, use [Company metrics](/mcp/tools/company-metrics). For sector-level statistics, use [Aggregate companies](/mcp/tools/aggregate-companies). To find company IDs first, use [Find company](/mcp/tools/find-company) or [Look up companies by tax ID](/mcp/tools/lookup-companies-by-tax-id) for batch resolution.

## Arguments

<ParamField type="string[]">
  List of company IDs from [`syrto_find_company`](/mcp/tools/find-company) or [`syrto_lookup_companies_by_tax_id`](/mcp/tools/lookup-companies-by-tax-id). Minimum 2, maximum 20.
</ParamField>

<ParamField type="string[]">
  Metric code slugs to compare (min 1, max 10). Examples: `["ebitda", "roe", "net_financial_position"]`. Use [`syrto_search_metric_definitions`](/mcp/tools/metric-definitions) or [`syrto_list_available_metrics`](/mcp/tools/list-available-metrics) to find valid slugs.
</ParamField>

<ParamField type="integer">
  Fiscal year for comparison (e.g. `2023`).
</ParamField>

<ParamField type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

## Returns

A JSON object with per-company results and a list of any unrecognized company IDs.

<ResponseField name="companies" type="object[]">
  One entry per requested company (in the same order as `company_ids`), each with `company_id`, `legal_name`, and a `years` array.
</ResponseField>

<ResponseField name="companies[].years" type="object[]">
  One entry per fiscal year. Each contains:

  * `year` - fiscal year
  * `size` - EU SME classification
  * `employee_count` - headcount (`null` if unavailable)
  * `metrics` - list of metric objects
</ResponseField>

<ResponseField name="companies[].years[].metrics" type="object[]">
  One entry per requested metric slug, each with:

  * `name` - human-readable metric name
  * `slug` - internal identifier
  * `value` - numeric value (or `null` if unavailable)
  * `better_when` - object with `when_type`: `"HIGHER"`, `"LOWER"`, `"NEAR_TARGET"`, or `null`
</ResponseField>

<ResponseField name="missing_company_ids" type="string[]">
  Company IDs from the request that were not found.
</ResponseField>

<ResponseField name="note" type="string">
  Context note about data availability and where to find more on syrto.ai.
</ResponseField>

<ResponseField name="source_url" type="string">
  Link to the Syrto web app, where you can explore more data and insights.
</ResponseField>

<ResponseField name="warning" type="string | null">
  Present when metric slugs were not recognized (no data returned for any company).
</ResponseField>

## Example

**Compare EBITDA and ROE for two companies:**

```json theme={null}
{
  "company_ids": ["Zm86SVRfMDE2NTQwMTAzNDVfVTox", "Zm86SVRfMDAxNTk1NjAzNjZfVTox"],
  "metric_slugs": ["ebitda", "roe"],
  "year": 2023
}
```

**Result:**

* Returns each company with the requested metrics for the specified year
* Check `missing_company_ids` to verify all requested companies were found


# Financial statements
Source: https://docs.syrto.ai/mcp/tools/financial-statements

List, preview, and generate filled financial statements for a company.

Three tools work together to produce financial statements:

| Tool                                       | Purpose                                                |
| ------------------------------------------ | ------------------------------------------------------ |
| `syrto_list_financial_statement_templates` | Discover what statement formats are available          |
| `syrto_get_financial_statement_template`   | Preview the blank structure of a template              |
| `syrto_generate_financial_statement`       | Generate a statement filled with actual company values |

***

## List templates

`syrto_list_financial_statement_templates` returns all available financial statement formats.

### Arguments

<ParamField type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

### Returns

A JSON list of templates, each with:

<ResponseField name="template_slug" type="string">
  Template identifier - pass this to `syrto_get_financial_statement_template` or `syrto_generate_financial_statement`.
</ResponseField>

<ResponseField name="display_name" type="string">
  Human-readable template name.
</ResponseField>

<ResponseField name="countries" type="string">
  Country/region applicability (e.g. `"IT"`, `"*"`).
</ResponseField>

***

## Get template structure

`syrto_get_financial_statement_template` returns the blank line-item structure of a template, without any company values filled in.

### Arguments

<ParamField type="string">
  Template slug from `syrto_list_financial_statement_templates`.
</ParamField>

<ParamField type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

### Returns

<ResponseField name="result" type="string">
  Markdown template with `(syrto_code)` placeholders where values will be injected.
</ResponseField>

***

## Generate a statement

`syrto_generate_financial_statement` fetches company metric values and injects them into the chosen template(s), producing a filled statement in markdown.

### Arguments

<ParamField type="string">
  The company ID from [`syrto_find_company`](/mcp/tools/find-company).
</ParamField>

<ParamField type="string[]">
  One or more template slugs (e.g. `["italian_income_statement"]`). Use `syrto_list_financial_statement_templates` to discover available slugs. You can request multiple templates in a single call.
</ParamField>

<ParamField type="integer">
  Fiscal year to generate for (e.g. `2022`). Defaults to the most recent available year.
</ParamField>

<ParamField type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

### Returns

A JSON list of generated statements, each with:

<ResponseField name="company_name" type="string">
  Legal name.
</ResponseField>

<ResponseField name="year" type="integer">
  Fiscal year of the generated statement.
</ResponseField>

<ResponseField name="template_name" type="string">
  Human-readable template title.
</ResponseField>

<ResponseField name="template_slug" type="string">
  Internal template identifier.
</ResponseField>

<ResponseField name="metrics_matched" type="integer">
  Number of line items successfully filled with values.
</ResponseField>

<ResponseField name="total_slots" type="integer">
  Total number of line items in the template.
</ResponseField>

<ResponseField name="content" type="string">
  Markdown with values injected inline as **bold numbers**.
</ResponseField>

<ResponseField name="note" type="string">
  Context note about data availability and where to find more on syrto.ai.
</ResponseField>

<ResponseField name="source_url" type="string">
  Link to the Syrto web app, where you can explore more data and insights.
</ResponseField>

### Example

**Generate Barilla's income statement for 2022:**

```json theme={null}
{
  "company_id": "Zm86SVRfMDE2NTQwMTAzNDVfVTox",
  "template_slugs": ["italian_income_statement"],
  "year": 2022,
  "language": "en"
}
```

**Result:**

* Returns a filled income statement in markdown with metric values injected inline as **bold numbers**
* `metrics_matched` shows how many line items were successfully populated out of `total_slots`


# Find company
Source: https://docs.syrto.ai/mcp/tools/find-company

Look up a company by name or Italian tax ID to get its company ID.

`syrto_find_company` resolves a company name or Italian tax ID (codice fiscale) into a `company_id`. Most Syrto tools require a `company_id`, so this is typically the first step when analysing a specific company.

## Use this tool to

* Look up any Italian company by name or tax ID (codice fiscale)
* Get the `company_id` required by most other Syrto tools

## Arguments

<ParamField type="string">
  Company name or Italian tax ID (max 200 characters). For names, pass only the distinctive part - strip any legal form suffix (S.p.A., S.r.l., S.r.l.s., S.a.s., S.n.c.). Partial matches work.

  **Examples:**

  * `"Barilla"` (not "Barilla G. e R. Fratelli S.p.A.")
  * `"Ferrari"`
  * `"00159560366"` (codice fiscale)
</ParamField>

## Returns

A JSON list of matching companies. Each item contains:

<ResponseField name="id" type="string">
  The `company_id` to pass to all other Syrto tools.
</ResponseField>

<ResponseField name="legal_name" type="string">
  The official registered company name.
</ResponseField>

<ResponseField name="tax_id" type="string | null">
  Italian tax identifier (codice fiscale). `null` if not available.
</ResponseField>

<ResponseField name="note" type="string">
  Context note about data availability and where to find more on syrto.ai.
</ResponseField>

<ResponseField name="source_url" type="string">
  Link to the Syrto web app, where you can explore more data and insights.
</ResponseField>

<Note>
  If multiple companies match, the response will contain all of them - pick the correct one before passing the `company_id` to other tools.
</Note>

## Example

**Look up a company by name:**

```json theme={null}
{
  "query": "Barilla"
}
```

**Response:**

```json theme={null}
{
  "result": [
    {
      "id": "Zm86SVRfMDE2NTQwMTAzNDVfVTox",
      "legal_name": "BARILLA G. E R. FRATELLI - SOCIETÀ PER AZIONI",
      "tax_id": "01654010345"
    }
  ],
  "note": "Syrto data summary. More metrics, benchmarks, and insights are available at https://www.syrto.ai",
  "source_url": "https://app.syrto.ai"
}
```


# List available metrics
Source: https://docs.syrto.ai/mcp/tools/list-available-metrics

Browse all available Syrto financial metrics by type - use this to discover metric slugs before calling syrto_get_company_metrics.

`syrto_list_available_metrics` returns a catalogue of all available Syrto metrics, optionally filtered by type. Use it to discover metric slugs when you need to call [`syrto_get_company_metrics`](/mcp/tools/company-metrics) for metrics not already covered by [`syrto_get_company_analysis`](/mcp/tools/company-analysis).

<Tip>
  For general financial analysis, call `syrto_get_company_analysis` directly - no slug discovery needed. Only use this tool when you need to retrieve specific metrics (e.g. individual balance sheet line items) outside the four Syrto categories.
</Tip>

## Use this tool to

* Discover available metric slugs by type
* Build custom metric sets and confirm correct slug names
* Browse all available Syrto metrics

**Related tools:** For metric formulas and definitions, use [Metric definitions](/mcp/tools/metric-definitions). For actual metric values, use [Company metrics](/mcp/tools/company-metrics).

## Arguments

<ParamField type="string">
  Optional filter. One of: `"balance_sheet_item"`, `"financial_ratio"`, `"profitability"`, `"liquidity"`, `"solvency"`, `"structure"`, `"spider_graph_axes"`, `"spider_graph"`, `"Group of Variables"`.
  If omitted, returns a compact catalogue of all metrics grouped by type.
</ParamField>

<ParamField type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

### Metric types

| Type                 | What it contains                                                                                                  |
| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `balance_sheet_item` | Raw balance sheet and income statement line items - revenue, costs, assets, liabilities (absolute figures in EUR) |
| `financial_ratio`    | Other calculated ratios and indices not in the four Syrto categories (e.g. composite scores, radar components)    |
| `profitability`      | Profitability metrics - EBITDA, EBIT, ROE, ROA, margins, returns                                                  |
| `liquidity`          | Liquidity metrics - working capital, cash conversion cycle, current ratio                                         |
| `solvency`           | Solvency metrics - debt ratios, coverage ratios, leverage, financial sustainability                               |
| `structure`          | Structure metrics - asset composition, capital structure, capex intensity                                         |
| `spider_graph_axes`  | Individual axes used in spider graph visualizations - each axis represents a specific financial dimension         |
| `spider_graph`       | Composite spider graph templates that group multiple axes into thematic financial breakdowns                      |
| `Group of Variables` | Grouped variable sets used for composite calculations and aggregated indicators                                   |

## Returns

<ResponseField name="total_metrics" type="integer">
  Total number of metrics across all types.
</ResponseField>

<ResponseField name="categories" type="object[]">
  List of metric type groups, each with:

  * `type` - metric category name
  * `count` - number of metrics in this group
  * `metrics` - list of metric entries

  **Compact mode** (no `metric_type`): each metric has `slug` and `name` only.

  **Detailed mode** (with `metric_type`): each metric also includes `description`, unit of measure, and `better_if` direction.
</ResponseField>

<ResponseField name="note" type="string">
  Context note about data availability and where to find more on syrto.ai.
</ResponseField>

<ResponseField name="source_url" type="string">
  Link to the Syrto web app, where you can explore more data and insights.
</ResponseField>

<Note>
  The `slug` is an internal identifier. Use the human-readable `name` field for display.
</Note>

## Typical workflow

1. Call `syrto_list_available_metrics` with `metric_type="balance_sheet_item"` or `"financial_ratio"` to browse available slugs
2. Identify the slugs relevant to your question
3. Pass those slugs to [`syrto_get_company_metrics`](/mcp/tools/company-metrics)

## Example

**Get full details for balance sheet metrics:**

```json theme={null}
{
  "metric_type": "balance_sheet_item"
}
```

**Result:**

* Returns all balance sheet item metrics with full details: name, slug, description, unit, and direction
* Pick the slugs you need (e.g. `revenues`, `total_assets`), then pass them to `syrto_get_company_metrics`


# Look up companies by tax ID
Source: https://docs.syrto.ai/mcp/tools/lookup-companies-by-tax-id

Batch resolve up to 20 tax IDs to company IDs in a single call.

`syrto_lookup_companies_by_tax_id` resolves a list of Italian tax IDs (codice fiscale or partita IVA) into `company_id` values. Each tax ID is checked against both the EU VAT number and the taxpayer identification number on file.

<Tip>
  For looking up a single company by name or tax ID, use [`syrto_find_company`](/mcp/tools/find-company) instead. This tool is designed for batch resolution when you already have multiple tax IDs.
</Tip>

## Use this tool to

* Resolve multiple tax IDs to company IDs in one call (up to 20)
* Check which tax IDs match a known company and which do not
* Get the `company_id` required by most other Syrto tools when starting from tax identifiers

**Related tools:** For single-company lookup by name or tax ID, use [Find company](/mcp/tools/find-company).

## Arguments

<ParamField type="string[]">
  List of tax IDs to resolve (min 1, max 20). Each entry can be up to 200 characters. Each tax ID is matched against both EU VAT number and taxpayer identification number fields.

  **Example:** `["01654010345", "00159560366"]`
</ParamField>

<ParamField type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

## Returns

A JSON list in the same order as the input `queries`. Each item contains:

<ResponseField name="query" type="string">
  The original tax ID from the request.
</ResponseField>

<ResponseField name="status" type="string">
  `"resolved"` if a matching company was found, `"not_found"` otherwise.
</ResponseField>

<ResponseField name="company" type="object | null">
  Present when `status` is `"resolved"`. Contains:

  * `id` - the `company_id` to pass to all other Syrto tools
  * `legal_name` - official registered company name
  * `eu_vat_number` - EU VAT number (`null` if not available)
  * `taxpayer_identification_number` - Italian codice fiscale (`null` if not available)
</ResponseField>

<ResponseField name="note" type="string">
  Context note about data availability and where to find more on syrto.ai.
</ResponseField>

<ResponseField name="source_url" type="string">
  Link to the Syrto web app, where you can explore more data and insights.
</ResponseField>

## Example

**Resolve two tax IDs:**

```json theme={null}
{
  "queries": ["01654010345", "00000000000"]
}
```

**Response:**

```json theme={null}
{
  "result": [
    {
      "query": "01654010345",
      "status": "resolved",
      "company": {
        "id": "Zm86SVRfMDE2NTQwMTAzNDVfVTox",
        "legal_name": "BARILLA G. E R. FRATELLI - SOCIETÀ PER AZIONI",
        "eu_vat_number": "01654010345",
        "taxpayer_identification_number": "01654010345"
      }
    },
    {
      "query": "00000000000",
      "status": "not_found",
      "company": null
    }
  ],
  "note": "Syrto data summary. More metrics, benchmarks, and insights are available at https://www.syrto.ai",
  "source_url": "https://app.syrto.ai"
}
```


# Metric definitions
Source: https://docs.syrto.ai/mcp/tools/metric-definitions

Search for financial metric definitions, formulas, and causal relationships.

`syrto_search_metric_definitions` returns full metric definitions including the name, description, calculation formula, unit of measure, direction (better if higher/lower/near target), and dependency links showing the causal chain between metrics.

## Use this tool to

* Understand what a specific financial metric means, how it's calculated, and what drives it
* Explore causal relationships between metrics and identify dependencies
* Resolve a metric name to its slug before calling [`syrto_get_company_metrics`](/mcp/tools/company-metrics)

## Arguments

<ParamField type="string">
  Keyword (e.g. `"profitability"`, `"working capital"`, `"debt"`) or exact slug (e.g. `"ebitda"`, `"roe"`, `"net_working_capital"`). Exact slug lookup always returns a single result instantly.
</ParamField>

<ParamField type="integer">
  Maximum results for keyword search. Default `5`, maximum `20`. Ignored for exact slug matches.
</ParamField>

<ParamField type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

## Returns

A JSON list of metric definitions, each containing:

<ResponseField name="name" type="string">
  Human-readable metric name.
</ResponseField>

<ResponseField name="syrto_code" type="string">
  Internal metric identifier (slug). Use as input to `syrto_get_company_metrics` via the `metric_slugs` parameter. Use `name` for display.
</ResponseField>

<ResponseField name="short_name" type="string | null">
  Abbreviated metric name, if available.
</ResponseField>

<ResponseField name="description" type="string">
  Plain-language explanation of what the metric measures.
</ResponseField>

<ResponseField name="type" type="string">
  Metric category.
</ResponseField>

<ResponseField name="uom" type="string">
  Unit of measure (e.g. `"EUR"`, `"%"`, `"ratio"`).
</ResponseField>

<ResponseField name="better_if" type="string">
  `"HIGHER"`, `"LOWER"`, or `"NEAR_TARGET"`.
</ResponseField>

<ResponseField name="better_if_target" type="float | null">
  Target value when `better_if` is `"NEAR_TARGET"`. `null` for `HIGHER` or `LOWER` metrics.
</ResponseField>

<ResponseField name="fraction_digits" type="integer">
  Number of decimal places for displaying the metric value.
</ResponseField>

<ResponseField name="calculation_formula" type="string">
  How the metric is computed.
</ResponseField>

<ResponseField name="affects" type="string[]">
  Metrics this one feeds into.
</ResponseField>

<ResponseField name="is_affected_by" type="string[]">
  Metrics that drive this one.
</ResponseField>

<ResponseField name="note" type="string">
  Context note about data availability and where to find more on syrto.ai.
</ResponseField>

<ResponseField name="source_url" type="string">
  Link to the Syrto web app, where you can explore more data and insights.
</ResponseField>

## Example

**Look up EBITDA and its dependencies:**

```json theme={null}
{
  "query": "ebitda"
}
```

**Response (abbreviated):**

```json theme={null}
[
  {
    "name": "EBITDA",
    "syrto_code": "ebitda",
    "short_name": "EBITDA",
    "description": "Earnings before interest, taxes, depreciation, and amortisation. Measures operating profitability before non-cash charges.",
    "type": "profitability",
    "uom": "EUR",
    "better_if": "HIGHER",
    "better_if_target": null,
    "fraction_digits": 2,
    "calculation_formula": "Operating profit + Depreciation + Amortisation",
    "affects": ["EBITDA Margin", "Net Financial Position / EBITDA"],
    "is_affected_by": ["Revenues", "Operating Costs"],
    "note": "..."
  }
]
```


# Search companies
Source: https://docs.syrto.ai/mcp/tools/search-companies

Find Italian companies by sector, location, size, financial filters, or natural language description.

`syrto_search_companies` finds companies matching structured criteria - sector, region, size, employee count, financial metrics, or a natural language description. Unlike [`syrto_find_company`](/mcp/tools/find-company) (which searches by name or tax ID), this tool filters by business characteristics.

<Tip>
  If you need the **total count** of matching companies or aggregate statistics (average revenue, median EBITDA, etc.), use [`syrto_aggregate_companies`](/mcp/tools/aggregate-companies) instead - this tool only returns paginated results.
</Tip>

## Use this tool to

* Find companies in a specific sector, region, or size class
* Search by a natural language description of what the company does
* Filter companies by financial metric values (e.g. revenue above a threshold)

**Related tools:** For lookup by company name or tax ID, use [Find company](/mcp/tools/find-company). For aggregate statistics, use [Aggregate companies](/mcp/tools/aggregate-companies).

## Arguments

<ParamField type="string (JSON object)">
  Company profile filters as a JSON object. All fields are optional:

  | Field                                      | Type   | Description                                                                                                                                         |
  | ------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `nace`                                     | string | EU NACE sector code. Auto-detects level: section letter (`A`–`U`), division (2 digits, e.g. `"10"`), group (e.g. `"10.1"`), class (e.g. `"10.11"`). |
  | `nuts`                                     | string | EU NUTS region code. Auto-detects level: level 1 (3 chars, e.g. `"ITH"`), level 2 (4 chars, e.g. `"ITH3"`), level 3 (5 chars, e.g. `"ITH35"`).      |
  | `semantic_search`                          | string | Natural language description to search company profiles (max 500 characters, e.g. `"renewable energy solar panels"`).                               |
  | `age`                                      | object | Company age filter with `min` and/or `max` in years. E.g. `{"min": 5, "max": 20}`.                                                                  |
  | `shareholder_age`                          | object | Average age of shareholders with `min` and/or `max` in years. E.g. `{"min": 50, "max": 70}`.                                                        |
  | `beneficial_owner_age`                     | object | Average age of beneficial owners with `min` and/or `max` in years. E.g. `{"min": 40, "max": 65}`.                                                   |
  | `executive_officer_age`                    | object | Average age of executive officers (CEOs, managing directors) with `min` and/or `max` in years.                                                      |
  | `representation_and_authority_officer_age` | object | Average age of officers with representation and signing authority, with `min` and/or `max` in years.                                                |
  | `target_market`                            | string | One of: `B2B`, `B2C`, `B2G`, `B2B2C`, `B2B2G`, `C2C`, `C2B`, `G2C`, `G2B`.                                                                          |
  | `match_cutoff`                             | float  | Minimum semantic similarity score (0.0–1.0) when using `semantic_search`. Higher = fewer but more relevant matches.                                 |
  | `country_code`                             | string | ISO 3166-1 alpha-2 country code (e.g. `"IT"`).                                                                                                      |

  **Example:** `'{"nace": "C", "nuts": "ITH3", "age": {"min": 5}, "target_market": "B2B"}'`
</ParamField>

<ParamField type="integer">
  Fiscal year for annual data filters. **Required** when `size`, `metric_filters`, `employees`, or `radar` are used, or when sorting by metric.
</ParamField>

<ParamField type="string[]">
  One or more company size classifications: `"XS"`, `"S"`, `"M"`, `"L"` (e.g. `["S", "M"]`). Requires `year`.
</ParamField>

<ParamField type="string (JSON array)">
  Up to 10 metric value filters. Each object has `slug` (required), `min` (optional), `max` (optional). Requires `year`.

  Use [`syrto_search_metric_definitions`](/mcp/tools/metric-definitions) to find valid slugs.

  **Example:** `'[{"slug": "revenues_from_sales_and_services", "min": 1000000}]'`
</ParamField>

<ParamField type="string (JSON object)">
  Employee count filter with `min` and/or `max`. At least one is required. Requires `year`.

  **Example:** `'{"min": 50, "max": 500}'`
</ParamField>

<ParamField type="string (JSON object)">
  Filter by position on the Syrto Radar plane (0–100 on both axes). Combines via AND with all other filters. At least one of `size`, `efficiency`, or `polygon` is required. Requires `year`.

  | Field        | Type   | Description                                                                                                                                                                                                                                      |
  | ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | `size`       | object | Inclusive range on the Radar size axis with `min` and/or `max` (0–100). Distinct from the top-level `size` parameter (XS/S/M/L band).                                                                                                            |
  | `efficiency` | object | Inclusive range on the Radar efficiency axis with `min` and/or `max` (0–100).                                                                                                                                                                    |
  | `polygon`    | object | Arbitrary polygon over the (size, efficiency) plane. Has a `vertices` list of 3–64 points, each `{ "size": 0–100, "efficiency": 0–100 }`. Use axis ranges for rectangles or strips; use the polygon for triangles, L-shapes, or concave regions. |

  **Example (rectangle):** `'{"efficiency": {"min": 70}, "size": {"min": 40, "max": 80}}'`

  **Example (polygon):** `'{"polygon": {"vertices": [{"size": 0, "efficiency": 70}, {"size": 60, "efficiency": 100}, {"size": 100, "efficiency": 70}]}}'`
</ParamField>

<ParamField type="boolean">
  Filter by consolidated financial statements. Default: `false` (non-consolidated).
</ParamField>

<ParamField type="string (JSON object)">
  Sort configuration as a JSON object. Fields:

  | Field         | Type   | Description                                                                                                    |
  | ------------- | ------ | -------------------------------------------------------------------------------------------------------------- |
  | `field`       | string | `"match_score"` (default, meaningful with `semantic_search`) or `"metric"` (sort by a financial metric value). |
  | `direction`   | string | `"desc"` (default) or `"asc"`.                                                                                 |
  | `metric_slug` | string | Required when `field` is `"metric"`. The metric slug to sort by.                                               |

  **Example:** `'{"field": "metric", "metric_slug": "revenues_from_sales_and_services", "direction": "desc"}'`
</ParamField>

<ParamField type="string">
  Cursor for pagination. Pass the `end_cursor` value from a previous response to fetch the next page. Omit for the first page.
</ParamField>

<Note>
  At least one filter parameter must be provided. Returns up to 25 results per page - use the `end_cursor` from the response as the `after` parameter to fetch the next page.
</Note>

## Returns

<ResponseField name="has_next_page" type="boolean">
  Whether more results are available beyond the current page.
</ResponseField>

<ResponseField name="items" type="object[]">
  List of matching companies (up to 25), each with:

  * `id` - the `company_id` to pass to other Syrto tools
  * `legal_name` - official registered company name
  * `tax_id` - Italian tax identifier (`null` if not available)
  * `match_score` - semantic similarity score (`float`, only present when `semantic_search` is used)
  * `short_description` - brief description of the company's activity (only present when `semantic_search` is used)
  * `metrics` - list of metric objects with `name`, `slug`, `value`, `better_when` (only present when `metric_filters` or `sort_by` with `field: "metric"` is used)
</ResponseField>

<ResponseField name="end_cursor" type="string | null">
  Cursor token for fetching the next page. Pass this as the `after` parameter. `null` when there are no more pages.
</ResponseField>

<ResponseField name="note" type="string">
  Context note about data availability and where to find more on syrto.ai.
</ResponseField>

<ResponseField name="source_url" type="string">
  Link to the Syrto web app, where you can explore more data and insights.
</ResponseField>

## Example

**Find large manufacturers in Emilia-Romagna:**

```json theme={null}
{
  "anagraphic_filters": "{\"nace\": \"C\", \"nuts\": \"ITH5\"}",
  "year": 2023,
  "size": ["L"]
}
```

**Result:**

* Filters for NACE section C (manufacturing), NUTS level 2 ITH5 (Emilia-Romagna), size L (large)
* Returns up to 25 companies per page; pass `end_cursor` as `after` to fetch additional pages


# Spider graphs
Source: https://docs.syrto.ai/mcp/tools/spider-graphs

Get thematic financial performance across spider graph axes for a company.

`syrto_get_spider_data` returns performance scores across N thematic axes per template (e.g. operational profitability, autonomy, capacity, operating cash flow, reliability). Each axis has a normalised value from 0 to 5.

## Radar vs. spider

Spider graphs are distinct from the radar chart:

|             | Radar                                                      | Spider                                                    |
| ----------- | ---------------------------------------------------------- | --------------------------------------------------------- |
| **Tool**    | `syrto_get_company_analysis` / `syrto_get_company_metrics` | `syrto_get_spider_data`                                   |
| **Axes**    | 2 (Efficiency, Size)                                       | N thematic axes per template                              |
| **Scale**   | 0–100                                                      | 0–5                                                       |
| **Answers** | "Where does this company stand overall?"                   | "How does it perform on profitability / autonomy / etc.?" |

## Use this tool to

* Get a thematic financial breakdown across axes like operating profitability, autonomy, or cash flow
* Compare performance across financial themes
* Drill into specific areas after a general [Company analysis](/mcp/tools/company-analysis)

## Arguments

<ParamField type="string">
  The company ID from [`syrto_find_company`](/mcp/tools/find-company).
</ParamField>

<ParamField type="integer">
  Year to retrieve (e.g. `2022`). If omitted, returns the most recent year plus the prior year (controlled by `include_prior_year`).
</ParamField>

<ParamField type="boolean">
  When `true` (default), returns the most recent year plus the prior year for trend context. When `false`, returns only the most recent year. Ignored when `year` is provided.
</ParamField>

<ParamField type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

## Returns

A JSON object with `company_name`, `available_years`, and per-year spider data. Each year contains a list of spider templates:

<ResponseField name="available_years" type="integer[]">
  All years with spider data for this company.
</ResponseField>

<ResponseField name="display_name" type="string">
  Human-readable template name (use this for display, not `template_slug`).
</ResponseField>

<ResponseField name="template_slug" type="string">
  Internal template identifier.
</ResponseField>

<ResponseField name="axes" type="object[]">
  List of axes, each with:

  * `display_name` - human-readable axis name
  * `template_slug` - internal axis identifier
  * `current_value.value` - score from 0 to 5
</ResponseField>

<ResponseField name="note" type="string">
  Context note about data availability and where to find more on syrto.ai.
</ResponseField>

<ResponseField name="source_url" type="string">
  Link to the Syrto web app, where you can explore more data and insights.
</ResponseField>

## Example

**Spider breakdown for Barilla:**

```json theme={null}
{
  "company_id": "Zm86SVRfMDE2NTQwMTAzNDVfVTox"
}
```

**Response (abbreviated):**

```json theme={null}
{
  "result": {
    "company_name": "BARILLA G. E R. FRATELLI - SOCIETÀ PER AZIONI",
    "years": [
      {
        "year": 2024,
        "spiders": [
          {
            "display_name": "Management Style",
            "axes": [
              { "display_name": "Stability", "current_value": { "value": 2.0 } },
              { "display_name": "Operating Profitability", "current_value": { "value": 2.75 } },
              { "display_name": "Autonomy", "current_value": { "value": 2.33 } }
            ]
          }
        ]
      }
    ]
  },
  "note": "Syrto data summary. More metrics, benchmarks, and insights are available at https://www.syrto.ai",
  "source_url": "https://app.syrto.ai"
}
```