We are currently building something exciting and will be launching soon. Registration is temporarily closed. Launching soon — registration temporarily closed.

Emotion Analysis API

Detect 20 distinct emotions in text.

The Emotion Analysis API classifies submitted text against 20 emotions in 16 supported languages with a flat taxonomy.

The API returns the top-3 emotions with signal-match scores. Use the results to enrich customer feedback analysis, social media monitoring, support prioritization, content recommendation, and wellness screening workflows.

POST /v1/analyze · REST · JSON · Bearer authentication

Scope

Sentiqra analyzes emotion signals contained in the text you submit. It does not diagnose mental health conditions, determine psychological states, or replace clinical or professional review.

Make your first request

curl -X POST https://sentiqra.tech/v1/analyze \
  -H "Authorization: Bearer $SENTIQRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I have been waiting three weeks for a response and nobody seems to care about my issue.",
    "language": "en",
    "analyzers": [
        "emotions"
    ]
}'

Example response:

{
    "language": "en",
    "language_source": "declared",
    "signals": [
        {
            "analyzer": "emotions",
            "code": "negative_emotion",
            "label": "Negative Emotion",
            "score": 0.95,
            "level": "category"
        },
        {
            "analyzer": "emotions",
            "code": "frustration",
            "label": "Frustration",
            "score": 0.93,
            "level": "label",
            "parent": "negative_emotion"
        },
        {
            "analyzer": "emotions",
            "code": "disappointment",
            "label": "Disappointment",
            "score": 0.87,
            "level": "label",
            "parent": "negative_emotion"
        }
    ],
    "meta": {
        "analyzers": [
            {
                "name": "emotions",
                "status": "completed",
                "applicability": "analyzable",
                "assessment": "signals_detected",
                "signal_count": 3,
                "billed": true
            }
        ]
    },
    "usage": {
        "analyzer_runs": 1
    },
    "verification": {
        "configuration": "sqcfg_3WTVYJV6",
        "fingerprint": "fp_8a72...19f",
        "input_commitment": "ic_31bd...a42",
        "signature": "sig_ed25519_4c1f...e2a",
        "key_id": "edk_af4f218e"
    }
}

Don't have an API key? Generate one from the API Keys page in your dashboard.

Endpoint

POST /v1/analyze

Classifies emotion signals in submitted text and returns the top-3 emotions with signal-match scores.

Request

{
    "text": "I have been waiting three weeks for a response and nobody seems to care about my issue.",
    "language": "en",
    "analyzers": [
        "emotions"
    ]
}

Parameters

Parameter Type Required Default Description
textstringYes-Text to analyze
languagestringNo"en"Supported language code
Advanced parameters →

Related endpoints

GET /v1/meta/domains/emotions

Identifier, availability, and endpoint for this analyzer. Send a Bearer API key for taxonomy summary and supported languages.

GET /v1/meta/domains

Lists all analyzers with identifiers, status, and endpoints - no authentication required. Send a Bearer API key for taxonomy size and language counts.

What the API can classify from text

Sentiqra can identify language associated with 20 distinct emotions:

Can classify from text

  • • Joy and excitement
  • • Sadness and loneliness
  • • Anger and contempt
  • • Fear and anxiety
  • • Surprise and confusion
  • • Love and gratitude

20 emotions in total - the complete list is available to customers after request access .

Requires external evidence

  • • Clinical mental health diagnosis
  • • Psychological state assessment
  • • Emotional intent vs. impact
  • • Longitudinal emotional patterns
  • • Contextual and situational factors
  • • Speaker's actual emotional state
  • • Sarcasm and irony disambiguation
  • • Cultural emotion expression norms

These are classification signals, not psychological assessments. For cases requiring external evidence, Sentiqra can provide one textual evidence layer for your broader analysis.

What requires additional evidence

Some emotion conclusions cannot be established from an isolated text item.

Clinical diagnosis

Determining mental health conditions requires assessment by qualified clinical personnel.

Actual emotional state

Text may not reflect the speaker's true emotional state - people may mask, exaggerate, or perform emotions.

Sarcasm and irony

Distinguishing genuine emotions from sarcastic or ironic expression may require contextual and conversational evidence.

Cultural context

Emotion expression norms vary by culture. Sentiqra does not apply culture-specific interpretation rules.

Longitudinal patterns

Establishing emotional trends over time requires multiple data points and temporal analysis.

Classification is not assessment

A typical emotion analysis workflow looks like:

Content
        ↓
Sentiqra emotion signals
        ↓
Context / policy / business logic / cultural factors
        ↓
Human or professional review
        ↓
Customer-defined decision

Sentiqra supplies structured classification evidence. Your organization determines whether further analysis, labeling, escalation, action, or no action is appropriate.

An empty result is not a verdict

When no emotion is detected above threshold, the API returns an empty signal set - not a low-confidence guess. This lets your workflow distinguish "no emotion detected" from "low-confidence emotion detected" without a fallback label to filter out.

An empty signals array alone does not establish that the content is neutral or benign. Check meta.analyzers[].status and assessment:

  • •completed / no_signals - the analyzer ran and nothing crossed threshold. Not proof of neutral content; genuinely flat text and borderline cases both land here.
  • •completed / abstained - a validated rejection rule found the input off-domain (e.g. too fragmentary to classify meaningfully). The analyzer declined to report - also not a neutral verdict.
  • •not_applicable - nothing ran: the declared language isn't covered (unsupported_language) or the text has no analyzable letters (insufficient_content). Route these separately - they are non-results.

Queue-routing rule: treat no_signals as "no actionable emotion signal", not as a finding that the text is emotionally neutral. See the production guide for the full conditions table.

Response structure

groups

Emotion categories, ranked by score (level: "category").

{
    "analyzer": "emotions",
    "code": "negative_emotion",
    "label": "Negative Emotion",
    "score": 0.95,
    "level": "category"
}

signals

Stable machine identifier for the signal. Use code when storing or cross-referencing signals (level: "label").

{
    "analyzer": "emotions",
    "code": "frustration",
    "label": "Frustration",
    "score": 0.93,
    "level": "label",
    "parent": "negative_emotion"
}

parent

Category slug this label-level signal belongs to. Dotted form is group.label - e.g. negative_emotion.frustration means frustration sits under negative_emotion.

Field Type Description
codestringStable machine identifier
labelstringHuman-readable display name
parentstringParent category code (label-level only)
scorefloatSignal-match strength (0.0–1.0)

Signal scores

A score expresses signal-match strength under a particular analyzer configuration. It is not a probability that the signal or a downstream action is correct. Validate action thresholds on representative labeled data.

Paid API keys receive the continuous score (profile full.v1); anonymous, playground, demo, and free-tier responses return banded scores with a confidence band (profile reduced.v1). See Understanding signals for the profile and band table.

It does not represent:

  • • Probability that the speaker actually felt the emotion
  • • Clinical or psychological assessment
  • • Emotional intensity or severity
  • • Sarcasm or irony disambiguation
  • • Justification for an automated action

Confidence should determine evidence strength - not workflow policy. Configure review thresholds according to emotion type, context, and your own labeled evaluation data.

Your application decides what happens next.

20 emotions in a flat taxonomy

The taxonomy uses a flat structure with 20 distinct emotions. Representative emotions are shown publicly - the complete list is available to customers after request access .

Joy
Sadness
Anger
Fear
Surprise
Disgust
Love
Pride
Shame
Hope

Deterministic classification

For the same normalized input evaluated against the same supported pinned configuration and output profile, Sentiqra returns the same canonical signals.

Version changes are explicit so historical and current analyzer behavior can be distinguished.

Supported languages

Emotion Analysis currently supports 16 languages.

Code Language Status
en English Production
fr French Production
es Spanish Production
de German Production
it Italian Production
nl Dutch Production
no Norwegian Production
pl Polish Production
uk Ukrainian Production
ru Russian Production
sv Swedish Production
fi Finnish Production
lv Latvian Production
lt Lithuanian Production
pt Portuguese Production
tr Turkish Production

All languages this detector supports are enabled on every plan. Custom or restricted arrangements may scope language access - check the dashboard or GET /v1/account/entitlements for account-specific availability.

Detector does not support language → 400 unsupported_language
Detector supports language but the account is not entitled (restricted/custom arrangements only - GA plans include all supported languages) → 403 language_not_in_plan

View language coverage and benchmarks →

Performance

Built for real-time emotion analysis pipelines.

p50 < 200ms
Median response time (single request)
p95 < 500ms
95th percentile latency - published target

Published latency targets, not measured guarantees - measured snapshot figures are on the performance dashboard. Actual latency depends on network conditions, payload size, and load.

Errors, limits, and rate controls

The Emotions API uses standard HTTP response codes:

Code Description
400Invalid request
401Authentication error
403Access unavailable
413Input too large
429Rate or quota exceeded
500Internal error
503Temporary unavailability

For retryable responses, follow documented backoff and Retry-After behavior.

Header Description
X-RateLimit-LimitMax requests per second
X-RateLimit-RemainingRemaining requests in current window
X-RateLimit-ResetUnix timestamp when window resets
View current pricing and limits →

Data handling

Sentiqra documents separately what crosses and remains within the service boundary:

Raw request content

Submitted text is processed in memory and not retained. No model training on your data.

Signal metadata

Individual signal results are not stored. Only aggregate counters are derived from them before the response is sent, apart from the bounded idempotency replay copy and webhook delivery payloads described in the retention schedule.

Operational metadata

Request status, key identifiers, latency, and billing information are logged for operational purposes.

Code examples

All examples use environment variables for API keys - do not hard-code keys in source.

curl -X POST https://sentiqra.tech/v1/analyze \
  -H "Authorization: Bearer $SENTIQRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I have been waiting three weeks for a response and nobody seems to care about my issue.",
    "language": "en",
    "analyzers": [
        "emotions"
    ]
}'

Use an SDK

Official SDKs are available for Python, JavaScript, Go, and PHP.

View SDK preview →

Reading Emotion Analysis output

What you can safely infer from a result - and what you must not.

Intended task

Rank which of the 20 documented emotions a piece of text expresses - the emotional register of the writing.

Input requirements

  • text - the only field analyzed; up to 4,096 Unicode code points. Over the limit is rejected with input_too_long, never truncated.
  • language - must be a language this analyzer supports. Unsupported codes are rejected with 400 unsupported_language, never analyzed as a different language.
  • analyzers - include "emotions"; up to 2 analyzers per request, one billed run each.
  • No context beyond text - no user IDs, history, profiles, or attachments are read or inferred.
  • Short text works, but single words and fragments carry little signal - very thin input can return an empty result.

Ordinary positive

“I was dreading this release all week, but seeing it finally live - I am honestly so proud of the team.”

pride very high
relief high
excitement medium

Safe inference: The text expresses pride and relief with an excitement undertone - a ranked mix, not a single verdict.

Confusing negative · Reported speech

“The customer sounded angry. You must be furious about the delay.”

What happens: Anger signals can fire - the text describes and attributes emotion rather than expressing it. Signals reflect the emotional language in the text, which may belong to a described third party rather than the author.

Why it's tricky: Secondhand emotion, quoted feelings, and hypothetical phrasing ("you must be furious") share vocabulary with felt emotion. Read emotion signals as the register of the text, not a measurement of any person's actual state.

What you can safely infer

  • The emotional register of the text as written, ranked across the documented emotion set.
  • That mixed emotions are a normal result - consume the ranked list, not just the top label.

What you must not infer

  • ✕The author's actual mental or emotional state - text is evidence of language, not feeling.
  • ✕That a described emotion belongs to the author rather than someone they describe.
  • ✕That a flat or empty result means the author feels nothing - thin text is thin evidence.

Boundary: Emotion signals describe the emotional language in a text. They are not a mental-health assessment and say nothing about any person's actual state.