Pin analytics in Zoho Desk can be retrieved programmatically via a dedicated API endpoint that returns engagement data for pinned items. This guide walks you through calling that endpoint using the Zoho Desk API client.
Why this matters
If you manage a Zoho Desk knowledge base or support portal, understanding how pinned content performs helps you prioritise what stays visible to customers. Teams tracking article engagement or agent productivity often need pin analytics as part of broader reporting workflows. This is particularly useful when building dashboards or automating reporting outside the native Zoho Desk UI.
Step-by-step
Step 1. Ensure your Zoho Desk OAuth connection is active and your access token is valid. The API client handles token refresh automatically, but your initial connection must be established and stored. If you are using the Zpilot engine, the getzohoapi helper will retrieve and refresh credentials on your behalf. [7]
Step 2. Confirm that your OAuth scopes include the necessary Zoho Desk permissions. At minimum, your environment should have Desk.tickets.READ, Desk.basic.READ, and Desk.search.READ configured — these are part of the standard ZOHODESKSCOPES block. Without the correct scopes, the API will reject your request. [2]
Step 3. Instantiate the ZohoDeskApi client with a valid ZohoDeskClient. You will need your API domain, a current access token, and your organisation ID (orgid). If your orgid is not yet stored, the client can auto-discover it by calling getallorganizations and reading the first result from the returned list. [7]
Step 4. Call the pin analytics endpoint using the following method on your ZohoDeskApi instance:
result = api.get_pin_analytics(p={})This sends a GET request to /api/v1/doc/pinanalytics. The p parameter accepts an optional dictionary of query parameters — pass an empty dict if you have no filters to apply. [1]
Step 5. Parse the response. The method returns the raw API response as a Python object. Iterate over the returned data to extract the metrics relevant to your reporting needs. If you are using the Zpilot chat interface, the assistant will format key fields in plain text automatically. [5]
Step 6. If you are running this inside the Zpilot engine's test suite, you can exercise the endpoint through the DeskTestRunner class. Initialise the runner with your org_id and a risk level of "SAFE", call setup() to establish the connection, then invoke the analytics method directly. [8]
Common pitfalls
- Missing org ID: If
org_idis blank or not persisted in your connection record, the Desk client may fail silently or return an authorisation error. Always verify the org ID is populated before making calls. [7] - Expired tokens: The token refresher queries the database for the latest
refreshtokenand updates the storedaccesstokenon success. If the refresh itself fails — for example due to a revoked client secret — the refresher returnsNoneand subsequent API calls will fail. [7] - Scope gaps: The
ZOHODESKSCOPESconfiguration does not include a dedicated analytics scope by name. If Zoho adds scope enforcement for pin analytics in a future API version, you may need to add it to your.envconfiguration. [2] - Port conflicts: If you are running the Zpilot server locally, it must run on port 8080. Using any other port breaks the OAuth redirect URI and prevents token acquisition entirely. [6]
What to check
- Verify your
orgidis stored in thezohoconnectionsdatabase record before calling the endpoint — a missing org ID is the most common cause of silent failures. [7] - Confirm OAuth scopes in your
.envfile include at minimumDesk.basic.READandDesk.search.READto ensure the Desk API accepts your requests. [2] - Inspect the raw response from
getpinanalyticsfor an expecteddatakey or list structure before building any downstream reporting logic on top of it. [1]
---
*Beam Help is independent expert support for Zoho — we are not official Zoho support, and this guidance is based on API behaviour observed in the Zoho Desk REST API documentation and client implementations.*