Perspective API Retirement: Timeline, Impact, and a Migration Plan

Google's Perspective API has powered toxicity scoring for comment systems since 2017. That run is ending: Google announced the Perspective API retirement with a 2026 shutdown window, and teams that rely on comments:analyze need a plan.

This post covers what is retiring, what breaks, and a concrete migration path so your moderation keeps working after the shutdown.

What is being retired

Perspective API is being sunset as a public product. When the retirement completes:

• The commentanalyzer.googleapis.com/v1alpha1/comments:analyze endpoint stops accepting requests
• Attribute scores (TOXICITY, SEVERE_TOXICITY, INSULT, THREAT, IDENTITY_ATTACK, PROFANITY, SEXUALLY_EXPLICIT) stop being returned
• API keys tied to the project lose access
• No direct Google successor has been announced

If your product gates comments, chat, or forum posts on Perspective scores, the shutdown takes that gating down with it - unless you migrate first.

Timeline to plan around

Google confirms service remains active until December 31, 2026. See the official sunset announcement. The practical timeline for your team:

• Now - Inventory every call site that depends on Perspective attributes
• Before your last pre-shutdown release - Swap the endpoint and remap categories behind a single wrapper
• Before the shutdown date - Turn off the Perspective integration entirely and verify thresholds against the new provider
• After shutdown - Keep your category mapping documented for future policy audits

The mistake to avoid is migrating category logic in a hurry after the endpoint stops responding.

What breaks vs what keeps working

// This stops working when the retirement completes
const url = 'https://commentanalyzer.googleapis.com/v1alpha1/comments:analyze';

const res = await fetch(url, {
method: 'POST',
body: JSON.stringify({
  comment: { text: userComment },
  requestedAttributes: { TOXICITY: {}, THREAT: {} },
}),
});

const scores = await res.json(); // { attributeScores: {...} }

Your policy logic (thresholds, actions, review queues) keeps working - it just needs a new source of decisions. That is the part worth protecting: remap once, keep the rest.

Migration plan in four steps

1. Wrap every Perspective call in one function

Do not scatter the endpoint across your codebase. A single moderateText() wrapper means one swap migrates your entire product.

2. Map Perspective attributes to Vettly categories

// Perspective attribute -> Vettly category
const categoryMap: Record<string, string> = {
TOXICITY: 'harassment',
SEVERE_TOXICITY: 'harassment',   // calibrate independently
IDENTITY_ATTACK: 'hate_speech',
INSULT: 'harassment',
PROFANITY: 'profanity',
THREAT: 'violence',
SEXUALLY_EXPLICIT: 'sexual',
};

3. Replace the endpoint with Vettly's /v1/check

import { createClient } from '@vettly/sdk';

const vettly = createClient(process.env.VETTLY_API_KEY!);

async function moderateText(text: string) {
const result = await vettly.check({
  content: text,
  contentType: 'text',
  policyId: 'moderate',
});

return {
  action: result.action, // allow | warn | flag | block
  categories: result.categories,
  decisionId: result.decisionId,
};
}

4. Shadow test, calibrate, and roll out

Run both systems on a labeled sample before changing enforcement. These mappings are conceptual, not equivalent scores: toxicity, severe toxicity, and insult collapse into harassment. Measure false positives and missed abuse per language, tune each threshold independently, then canary traffic behind a rollback switch. Keep content unpublished or send it to review when checks fail. Complete the cutover before December 31, 2026. See the full rollout checklist.

Why this matters for compliance

Perspective never provided reporting, blocking, or audit trails. If you built those yourself, they keep working. If you deferred them, the retirement is a forcing function: Apple App Store Guideline 1.2 and Google Play's UGC policy both require filtering, reporting, blocking, and an audit trail - not just a toxicity score.