agent could not read Gainsight timeline notes: API returned HTML instead of plain text after the update

TL;DR

The notes did not disappear, they changed clothes. Timeline entries that used to arrive as plain text now arrive as HTML after a Gainsight update, and an agent expecting raw text either chokes, stores markup as if it were the note, or extracts nothing and reports the account as quiet. Parse the HTML properly into clean text, preserve the parts that carry meaning such as lists and links, reprocess the notes the agent mishandled, and add a format check so the next silent format change is caught by a test instead of by a CSM wondering why every account went quiet.

agent could not read Gainsight timeline notes: API returned HTML instead of plain text after the update

Use this when

• The agent returns empty, garbled, or markup filled summaries for Gainsight timeline notes since a recent update
• The same notes read perfectly in the Gainsight UI
• Other Gainsight objects the agent reads, such as accounts and scores, still parse normally

Not for this skill when

• The timeline entries really are empty because CSMs stopped logging, which a UI sample check will establish quickly
• The agent lost API access to timeline specifically, which returns permission errors rather than changed content

Steps

1. Capture a real payload before changing code. Fetch one timeline entry the agent mishandled, directly through the Gainsight API using the agents credentials, and save the raw response. Confirm the note field now carries HTML, note exactly which fields changed shape, and keep this response as the fixture every later fix is tested against, because testing against imagined payloads is how parsers pass review and fail production. Verify: the raw HTML carrying payload is captured and saved as a test fixture
2. Assess what the current parser did with HTML across the back catalogue. Determine whether it stored raw markup in summaries, stripped tags and lost structure, or dropped the entries entirely, and count affected notes by date from the update onward, since each failure mode needs a different cleanup and stakeholders need the size of the gap in the accounts histories the agent produced. Verify: the failure mode and affected note count are established
3. Implement proper HTML to text conversion. Use a real HTML parser rather than pattern matching, convert paragraph and list structure into readable plain text, keep link targets where the link text alone loses meaning, decode escaped entities, and handle malformed or partial markup defensively, because timeline notes are human written rich text pasted from many sources and will contain every nesting mistake imaginable. Verify: the converter produces clean readable text from the fixture including its lists, links, and entities
4. Add a contract test to the agent. Store representative timeline payloads, plain text legacy style and HTML current style, as fixtures and assert the extracted text in the agents test suite, and add a run time sanity check that flags when extracted note text suddenly drops in average length or arrives full of markup, so a future API format shift fails a test or an alert rather than a quarter of summaries. Verify: the fixture tests pass in the suite and the run time format check is in place
5. Reprocess the affected window. Re-run note extraction for every timeline entry since the format change, regenerate the summaries or risk inputs that consumed the broken text, and spot check several accounts with their CSMs, because they will spot meaning errors, a list flattened into a misleading sentence, that automated checks cannot judge. Verify: the affected window is reprocessed and CSM spot checks confirm readable, accurate notes
6. Engage the vendor change properly. Check the Gainsight release notes and your API version settings to learn whether the HTML format is the new contract or a version specific behaviour you can pin, record the finding in the integration runbook, and subscribe the integration owner to release notes for the products the agent reads, since format changes are announced far more often than they are noticed. Verify: the format status is confirmed from release documentation and recorded in the runbook

Why it happens

Rich text has to be stored somehow, and platforms periodically change their representation, from plain text fields to HTML, as their editors gain features. API consumers who treated the old representation as a permanent contract break in proportion to how literally they parsed it. The content never changed, only its encoding, which is why the fix belongs in a tolerant parsing layer with format fixtures, rather than in chasing Gainsight to change back for one integration.

Compatibility: Gainsight timeline and its API, HTML to text conversion, and agent integration testing, in current Gainsight versions.

Variants and edge cases

Gainsight timeline API returns HTML not plain text

['The direct phrasing. A real captured payload as a fixture is the foundation, build the fix and the regression test on the same artefact.']

agent cannot parse timeline notes after update

['The update variant. Pin or track API versions deliberately for agent integrations, silent upgrades to consumed formats are a recurring tax.']

timeline notes garbled markup in agent summaries

['The quality variant. Conversion quality matters beyond extraction, flattened lists and lost links change meaning, so include human spot checks in the acceptance pass.']

Edge cases to work through before you close the incident:

• Attachments and images inside notes will not convert to text. Preserve a reference to them in the extracted text so a reader knows content exists beyond the words.
• Sanitise converted content before it reaches summaries or prompts. HTML from any source should be treated as untrusted input even when the source is your own CS platform.
• Very long timeline histories need chunking after conversion, not before. Converting first gives an accurate length and avoids splitting a note mid tag.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstN8r-spncGvbYOkGortFAw