/entitlements/report - Add-on analytics within the caller's hierarchy

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://api.my.nethesis.it/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "my.nethesis.it MCP server": {
    "url": "https://api.my.nethesis.it/mcp"
  }
}
Close
GET /entitlements/report
Bearer auth

The commercial overview of the add-on grants the caller can see: lifecycle totals (active/expired/revoked/pending/suspended, perpetual, expiring in 30/60/90 days), the per-type breakdown, the renewal distribution and a 12-month activation trend. The per-organization and per-tier breakdowns live on their own paginated endpoints. Scope matches /entitlements/grants: the whole fleet for the owner organization / a Super Admin, the caller's own organization and its descendants otherwise. Deleted systems are excluded.

Responses

  • 200 application/json

    Entitlement report retrieved successfully

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object

      Fleet-wide add-on analytics (owner/Super Admin only)

      Hide data attributes Show data attributes object
      • totals object
        Hide totals attributes Show totals attributes object
        • total integer
        • active integer
        • expired integer
        • revoked integer
        • pending integer
        • suspended integer
        • perpetual integer

          Active grants without an expiry (legacy imports)

        • expiring_in_30d integer

          Active grants expiring within 30 days

        • expiring_in_60d integer

          Active grants expiring within 60 days (cumulative)

        • expiring_in_90d integer

          Active grants expiring within 90 days (cumulative)

        • systems integer

          Distinct systems with at least one grant

        • organizations integer

          Distinct organizations owning those systems

        • distributor_systems integer

          Systems owned by distributor organizations (the four *_systems fields sum up to systems)

        • reseller_systems integer

          Systems owned by reseller organizations

        • customer_systems integer

          Systems owned by customer organizations

        • owner_systems integer

          Systems owned by the owner organization

        • total_renewals integer

          Sum of renewal_count over all grants

      • by_entitlement array[object]

        Lifecycle breakdown per add-on type. Includes add-ons with no grant behind them (every count 0) so the report can surface what nobody has bought yet: the whole catalog for the owner organization and Super Admins, only what the caller's organization may buy for everyone else. An add-on the caller holds is always listed, even when it is no longer available or no longer in the catalog (then it is labelled by id). Counts are always bound to the caller's hierarchy.

        Hide by_entitlement attributes Show by_entitlement attributes object
        • entitlement string
        • display_name string
        • active integer
        • expired integer
        • revoked integer
        • pending integer
        • suspended integer
        • total integer
      • renewals object

        Renewal distribution across grants

        Hide renewals attributes Show renewals attributes object
        • never integer
        • once integer
        • twice integer
        • three_plus integer
      • trend array[object]

        Grants created per month, last 12 months

        Hide trend attributes Show trend attributes object
        • month string
        • activations integer
  • 401 application/json

    Unauthorized - invalid or missing token

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object | null
  • 403 application/json

    Forbidden - insufficient permissions

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object | null
  • 500 application/json

    Internal server error

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object | null
GET /entitlements/report 
curl \
 --request GET 'https://api.your-domain.com/api/entitlements/report' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "code": 200,
  "message": "entitlement report retrieved successfully",
  "data": {
    "totals": {
      "total": 120,
      "active": 95,
      "expired": 12,
      "revoked": 6,
      "pending": 3,
      "suspended": 4,
      "perpetual": 40,
      "expiring_in_30d": 8,
      "expiring_in_60d": 15,
      "expiring_in_90d": 22,
      "systems": 80,
      "organizations": 35,
      "distributor_systems": 20,
      "reseller_systems": 35,
      "customer_systems": 22,
      "owner_systems": 3,
      "total_renewals": 60
    },
    "by_entitlement": [
      {
        "entitlement": "nsec-blacklist",
        "display_name": "Advanced Threat Shield",
        "active": 60,
        "expired": 8,
        "revoked": 3,
        "pending": 2,
        "suspended": 1,
        "total": 74
      }
    ],
    "renewals": {
      "never": 70,
      "once": 30,
      "twice": 15,
      "three_plus": 5
    },
    "trend": [
      {
        "month": "2026-07",
        "activations": 9
      }
    ]
  }
}
Response examples (401) 
{
  "code": 401,
  "message": "invalid token",
  "data": {}
}
Response examples (403) 
{
  "code": 403,
  "message": "insufficient permissions",
  "data": {}
}
Response examples (500) 
{
  "code": 500,
  "message": "internal server error",
  "data": {}
}