> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidnavigator.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tweet Claim Analysis
> Fetches the tweet content (including any quoted tweet and attached media), then uses AI to extract a rich structured analysis: the core claim, classification axes, topics, entities, and raw tweet data.
**Multimodal media handling:** attached media is processed by type. Videos are transcribed (platform captions or speech-to-text) and summarized; images are described by a vision model — transcribed text, chart/graph data points, recognisable people and logos, and any claims they make — and folded into the analysis.
**Classification axes** (`claim_type`, `intent`, `tone`, `emotion`, `authority`) reflect **only the original tweet text**, not quoted content, media, or images.
**Billing (consolidated, mirrors `/v1/analyze/video`):**
- exactly one `analysis_request` charge with `quantity = ceil(total_tokens / 15000)`, summing tokens across the optional per-media extraction calls, the optional image vision calls, AND the main statement-extraction call. A typical tweet+quoted tweet with one video or an attached image runs several LLM calls but produces just one billing entry when the combined tokens stay under 15k. Image analysis is billed through this same `analysis_request` meter.
- one `standard_request` per media URL whose transcript or metadata is fetched (mirrors `/v1/transcript`).
- `transcription_hour` proportional to the audio duration if speech-to-text runs for a media video that has no platform transcript. Waived for users with `users.free_on_cache_hit=true` when STT was served from cache (same waiver as `/v1/transcribe`).
Extract the real meaning behind an X/Twitter post by analyzing the original tweet, any quoted tweet, and media shared in both contexts.
## Overview
This endpoint turns a single X post into a machine-readable intelligence object. It does not just retrieve tweet text or metadata. It analyzes what the author actually meant by combining the original tweet, any quoted tweet, and any media attached to either one.
That means the output reflects the full communicative intent of the post, not just the visible text. If a tweet makes sense only when read together with a quoted post, an attached video, or media inside the quoted tweet, this endpoint includes that context in the analysis.
It is designed for workflows that need more than keyword monitoring or tweet retrieval, such as fact-checking pipelines, narrative tracking, social risk monitoring, and structured ingestion into dashboards or AI systems.
This is **not** a basic tweet retrieval API. Its core value is intelligence extraction: understanding the author's intent, the role of the quoted tweet, and the meaning conveyed by media attached to both the original and quoted post.
### What This Endpoint Returns
Extract a multi-sentence `final_statement` that reflects what the author actually meant, not just what the raw tweet text says in isolation.
Incorporate quoted tweet context when the original post depends on it for meaning, stance, or narrative framing.
Classify the original tweet by `claim_type`, `intent`, `tone`, `emotion`, and `authority`.
Analyze media attached to the tweet and the quoted tweet. Videos are transcribed (platform captions or speech-to-text) and summarized; images are described by a vision model — transcribed text, chart/graph data points, recognizable people and logos, and any claims they make.
### Why This Endpoint Is Different
Most tweet APIs stop at text retrieval, engagement metrics, or shallow metadata. This endpoint is built for intelligence extraction.
* It understands the **intent** behind the original tweet.
* It understands the **quoted tweet** as part of the message, not as unrelated metadata.
* It analyzes **shared media in the original tweet** — both videos (transcribed) and images (described by a vision model).
* It analyzes **shared media in the quoted tweet**.
* It returns a structured output that reflects the **combined meaning** of all of that context.
This is especially important for X posts where the author's real point is only clear when you interpret the text together with a quoted post, a reaction clip, a narrated video, or media evidence embedded in either layer.
### How It Works
1. Send a `tweet_id` for the target X post.
2. VidNavigator fetches the original tweet, any quoted tweet, and media attached to both.
3. If video or audio is present in either context, the system retrieves transcripts or falls back to speech-to-text when needed. Attached images are described by a vision model.
4. The combined context is analyzed to determine the real claim, intent, framing, and supporting media meaning.
5. The result is returned as structured JSON ready for applications and pipelines.
This endpoint accepts a **tweet ID**, not a full URL. For example, from `https://x.com/user/status/1912345678901234567`, the `tweet_id` is `1912345678901234567`.
## Classification Axes
The classification labels below are derived from the **original tweet text only**, not from quoted tweets or attached media:
* `claim_type`: `factual_claim`, `opinion`, `question`, `call_to_action`, `satire`, `news_sharing`, `personal_experience`
* `intent`: `educate`, `inform`, `analyze`, `persuade`, `entertain`, `inspire`, `challenge`
* `tone`: `serious`, `humorous`, `provocative`, `neutral`, `warm`, `skeptical`, `inspirational`
* `emotion`: `curiosity`, `urgency`, `outrage`, `fear`, `hope_inspiration`, `confidence_reassurance`, `empathy_warmth`, `awe_wonder`
* `authority`: `data_driven`, `expert_led`, `experience_based`, `speculative`
## Example Usage
### Best For
Use this endpoint when you need to understand what a post is really saying, especially when meaning depends on:
* the author's underlying intent
* a quoted tweet that changes the framing
* attached video or audio in the original tweet
* attached video or audio in the quoted tweet
If you only need raw tweet metadata, this is more powerful than necessary. This endpoint is for interpretation and intelligence extraction.
### Basic Request
```bash cURL theme={null}
curl -X POST "https://api.vidnavigator.com/v1/tweet/statement" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tweet_id": "1912345678901234567"
}'
```
```python Python theme={null}
import requests
url = "https://api.vidnavigator.com/v1/tweet/statement"
headers = {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
data = {
"tweet_id": "1912345678901234567"
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print("Final statement:", result["data"]["final_statement"])
print("Claim type:", result["data"]["claim_type"])
print("Topics:", result["data"]["topics"])
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.vidnavigator.com/v1/tweet/statement', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
tweet_id: '1912345678901234567'
})
});
const result = await response.json();
console.log(result.data.final_statement);
```
### Example: Feeding Results into Search or Verification
When you want to take a tweet's interpreted meaning and use it for search, fact-checking, or evidence retrieval, the structured output is ready to plug into downstream pipelines:
```bash cURL theme={null}
curl -X POST "https://api.vidnavigator.com/v1/tweet/statement" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tweet_id": "1912345678901234567"
}'
```
Once returned, you can use:
* `final_statement` for human review or as a search/verification query
* `detailed_analysis` for framing and stance context
* `topics` and `entities` for clustering, tagging, or analytics
## Response Example
```json theme={null}
{
"status": "success",
"data": {
"final_statement": "The author claims that a new city policy will ban gas-powered delivery scooters in the downtown area next month, arguing that the change is being rushed without enough support for affected workers.",
"detailed_analysis": "The tweet presents a concrete policy claim and frames it as both imminent and harmful to delivery workers. The author positions the decision as poorly planned and emphasizes the lack of transition support. The message appears intended to persuade the audience that the policy is unfair rather than merely to report it. The framing combines factual assertion with rhetorical pressure.",
"topics": [
"urban policy",
"delivery workers",
"transport regulation",
"labor impact"
],
"entities": [
"City Council",
"downtown"
],
"claim_type": "factual_claim",
"intent": "persuade",
"tone": "provocative",
"emotion": "urgency",
"authority": "speculative",
"tweet_text": "Next month the city is banning gas scooters downtown and nobody has explained how delivery workers are supposed to adapt this fast.",
"tweet_media_summary": "A short attached video shows several delivery riders speaking about costs, route changes, and reduced earnings if the rule takes effect.",
"quoted_tweet_text": "Official announcement: downtown clean transport rules begin next month.",
"quoted_media_summary": null
}
}
```
## Field Guide
| Field | Description |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `final_statement` | Full normalized claim in the author's voice, informed by the full contextual analysis |
| `detailed_analysis` | 3-5 sentence explanation covering claim, framing, evidence, and stance |
| `topics` | Key subjects discussed in the tweet (3-8) |
| `entities` | Named entities such as people, organizations, or places (0-8) |
| `claim_type` / `intent` / `tone` / `emotion` / `authority` | Classification axes derived from the **original tweet text only** |
| `tweet_text` | Original text of the source tweet |
| `tweet_media_summary` | Full content summary of media attached to the original tweet: a video transcript summary **or** a vision-model description of attached image(s). `null` when no media is attached. |
| `quoted_tweet_text` | Text of a quoted or referenced tweet, when present |
| `quoted_media_summary` | Full content summary of media attached to the quoted tweet (video transcript or image description). `null` when no media is attached. |
## Intelligence Model
This endpoint should be thought of as a multi-layer interpretation pipeline:
1. Read the original tweet text.
2. Detect whether a quoted tweet changes or completes the meaning.
3. Analyze media attached to the original tweet.
4. Analyze media attached to the quoted tweet.
5. Produce a final claim and classification that reflect the author's intended message as completely as possible.
That is why the endpoint is effective for tweets where the visible text alone is incomplete, sarcastic, reactive, or dependent on embedded media.
## Billing Notes
Billing is **consolidated** and mirrors [`/analyze/video`](/api-reference/endpoint/analyze-video). A single call can involve several internal LLM calls (media extraction, image vision, and the main statement extraction) but produces **one** billing entry per meter:
* **Exactly one `analysis_request` charge** with `quantity = ceil(total_tokens / 15000)`, summing tokens across the optional per-media extraction calls, the optional image vision calls, and the main statement-extraction call. A typical tweet + quoted tweet with one video or one attached image runs several LLM calls but produces just one billing entry when the combined tokens stay under 15k. **Image analysis is billed through this same `analysis_request` meter.**
* **One `standard_request` per media URL** whose transcript or metadata is fetched (mirrors [`/transcript`](/api-reference/endpoint/transcript)).
* **`transcription_hour`** proportional to the audio duration if speech-to-text runs for a media video with no platform transcript. Waived for users with `free_on_cache_hit=true` when STT was served from cache.
For cost planning, a text-only tweet is typically simpler than a tweet with embedded media and a quoted post that also contains video or images.
## Use Cases
Convert noisy social posts into verification-ready claims that analysts can review quickly.
Group similar claims using `final_statement`, `topics`, and `entities` across many tweets.
Detect accusations, emotionally charged narratives, and emerging risk signals earlier.
Feed structured social intelligence into internal tools, LLM workflows, or search systems.
## Troubleshooting
* **Invalid tweet ID**: Make sure you are sending only the numeric post ID, not the full X URL.
* **Upstream fetch failure**: If X content cannot be retrieved or parsed, the endpoint may return a `502` response.
* **Missing media summary**: If no media is attached, or media could not be processed, `tweet_media_summary` and `quoted_media_summary` may be `null`.
* **Unexpected classification**: `claim_type`, `intent`, `tone`, `emotion`, and `authority` are based only on the original tweet text, while `final_statement` and media summaries reflect the broader contextual analysis.
## OpenAPI
````yaml POST /tweet/statement
openapi: 3.0.3
info:
title: VidNavigator Developer API
description: >-
The VidNavigator Developer API provides programmatic access to video
analysis, transcription, and search capabilities.
## Authentication
All endpoints require API key authentication via the `X-API-Key` header:
```
X-API-Key: YOUR_API_KEY
```
## Rate Limits
Check the documentation for the rate limits for each endpoint.
## Error Handling
The API uses standard HTTP status codes and returns error responses in JSON
format:
```json
{
"status": "error",
"error": "error_type",
"message": "Human readable error message"
}
```
version: 1.0.0
contact:
name: VidNavigator Support
url: https://vidnavigator.com/support
email: support@vidnavigator.com
license:
name: Proprietary
url: https://vidnavigator.com/terms
servers:
- url: https://api.vidnavigator.com/v1
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Transcripts
description: Extract transcripts from online videos
- name: TikTok
description: Scrape TikTok profile metadata and per-video stats
- name: Files
description: Manage uploaded audio/video files
- name: Analysis
description: AI-powered content analysis
- name: Extraction
description: >-
Extract structured data from video and file transcripts using custom
schemas
- name: Namespaces
description: Organize uploaded files into namespaces (folders)
- name: Search
description: Search videos and files using AI
- name: System
description: System health and information
- name: Tweet Analysis
description: Extract structured claims and metadata from X/Twitter tweets
paths:
/tweet/statement:
post:
tags:
- Tweet Analysis
summary: Extract structured claim from an X/Twitter tweet
description: >-
Fetches the tweet content (including any quoted tweet and attached
media), then uses AI to extract a rich structured analysis: the core
claim, classification axes, topics, entities, and raw tweet data.
**Multimodal media handling:** attached media is processed by type.
Videos are transcribed (platform captions or speech-to-text) and
summarized; images are described by a vision model — transcribed text,
chart/graph data points, recognisable people and logos, and any claims
they make — and folded into the analysis.
**Classification axes** (`claim_type`, `intent`, `tone`, `emotion`,
`authority`) reflect **only the original tweet text**, not quoted
content, media, or images.
**Billing (consolidated, mirrors `/v1/analyze/video`):**
- exactly one `analysis_request` charge with `quantity =
ceil(total_tokens / 15000)`, summing tokens across the optional
per-media extraction calls, the optional image vision calls, AND the
main statement-extraction call. A typical tweet+quoted tweet with one
video or an attached image runs several LLM calls but produces just one
billing entry when the combined tokens stay under 15k. Image analysis is
billed through this same `analysis_request` meter.
- one `standard_request` per media URL whose transcript or metadata is
fetched (mirrors `/v1/transcript`).
- `transcription_hour` proportional to the audio duration if
speech-to-text runs for a media video that has no platform transcript.
Waived for users with `users.free_on_cache_hit=true` when STT was served
from cache (same waiver as `/v1/transcribe`).
operationId: getTweetStatement
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- tweet_id
properties:
tweet_id:
type: string
description: The X/Twitter tweet ID (numeric string)
example: '1234567890123456789'
responses:
'200':
description: Successful extraction
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- success
data:
type: object
properties:
final_statement:
type: string
description: >-
Complete nuanced claim in the author's voice
(multi-sentence)
detailed_analysis:
type: string
description: >-
3-5 sentence breakdown: claim, context, evidence,
stance
topics:
type: array
items:
type: string
description: 3-8 key topics or subjects
entities:
type: array
items:
type: string
description: 0-8 proper nouns (people, organisations, places)
claim_type:
type: string
enum:
- factual_claim
- opinion
- question
- call_to_action
- satire
- news_sharing
- personal_experience
description: >-
Primary classification of the claim (based on original
tweet text only)
intent:
type: string
enum:
- educate
- inform
- analyze
- persuade
- entertain
- inspire
- challenge
description: >-
Primary intent of the tweet author (based on original
tweet text only)
tone:
type: string
enum:
- serious
- humorous
- provocative
- neutral
- warm
- skeptical
- inspirational
description: >-
Dominant tone of the tweet (based on original tweet
text only)
emotion:
type: string
enum:
- curiosity
- urgency
- outrage
- fear
- hope_inspiration
- confidence_reassurance
- empathy_warmth
- awe_wonder
description: >-
Primary emotion evoked by the tweet (based on original
tweet text only)
authority:
type: string
enum:
- data_driven
- expert_led
- experience_based
- speculative
description: >-
Type of authority backing the claim (based on original
tweet text only)
tweet_text:
type: string
nullable: true
description: The original tweet text
tweet_media_summary:
type: string
nullable: true
description: >-
Full content summary of media attached to the original
tweet: a video transcript summary, OR a vision-model
description of attached image(s) (transcribed text,
chart data, people/logos, claims). Null when no media
is attached.
quoted_tweet_text:
type: string
nullable: true
description: Text of the quoted/referenced tweet, if any
quoted_media_summary:
type: string
nullable: true
description: >-
Full content summary of media attached to the quoted
tweet (video transcript or image description). Null
when no media is attached.
'400':
description: Missing or invalid tweet_id
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: string
message:
type: string
'402':
$ref: d374cbe8-82dd-4718-86c0-9ca23161e787
'500':
$ref: '#/components/responses/InternalServerError'
'502':
description: Failed to fetch tweet from X API or AI could not extract a statement
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: string
message:
type: string
components:
responses:
InternalServerError:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: string
enum:
- internal_server_error
message:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: >-
API key authentication. Include your VidNavigator API key in the
X-API-Key header.
````