Get postcard status

Returns the current analysis state for a submitted URL. Use this endpoint to poll for progress after calling POST /api/postcards, and to retrieve the full forensic report once analysis completes. Method and path

GET https://postcard.fartlabs.org/api/postcards?url={url}

Request

Query parameters

url

string

required

The social media post URL being analyzed. Must exactly match the URL that was submitted to POST /api/postcards (the API normalizes both for comparison, so minor variations like trailing slashes are handled).

Responses

The response shape varies based on the current analysis state. All responses use Content-Type: application/json.

Processing (status: “processing”)

Returned while the analysis is queued or actively running. The stage and progress fields let you show a progress indicator.

status

string

required

"processing" — analysis is in progress.

string

UUID of the postcard record.

stage

string

Current pipeline stage key. One of: starting, scraping, scraped, corroborating, auditing, scoring, complete.

progress

number

A float from 0.0 to 1.0 representing overall pipeline completion. Useful for progress bars.

message

string

Human-readable description of the current stage (e.g., "Searching for primary sources...").

{
  "status": "processing",
  "stage": "corroborating",
  "message": "Searching for primary sources...",
  "progress": 0.4
}

Completed (status: “completed”)

The full forensic report is included in the response. No further polling is needed.

status

string

required

"completed".

url

string

required

The normalized URL that was analyzed.

platform

string

required

Detected platform: "X", "YouTube", "Reddit", "Instagram", or "Other".

postcardScore

number

required

Composite credibility score from 0.0 (low credibility) to 1.0 (high credibility).

markdown

string

required

Full extracted post content in Markdown format.

postcard

object

Structured metadata extracted from the post.

Show properties

platform

string

Platform enum: "X", "YouTube", "Reddit", "Instagram", or "Other".

mainText

string

Character-for-character extraction of the primary post content.

username

string

User handle (e.g., "@username").

timestampText

string

Relative or absolute post date as displayed on the platform (e.g., "2h ago").

engagement

object

Key/value map of engagement metrics (e.g., likes, retweets) as strings.

triangulation

object

Source triangulation metadata.

Show properties

targetUrl

string

The canonical URL of the post being analyzed.

queries

string[]

List of search queries generated during source triangulation.

audit

object

Origin and temporal audit scores.

Show properties

originScore

number

Score (0.0–1.0) reflecting how confidently the post’s origin was traced.

temporalScore

number

Score (0.0–1.0) reflecting temporal consistency between the post and corroborating sources.

totalScore

number

Combined audit score (0.0–1.0).

auditLog

string[]

Ordered list of audit reasoning steps as human-readable strings.

corroboration

object

Results of the AI-driven source corroboration pass.

Show properties

primarySources

object[]

Array of sources found during corroboration.

Show source properties

url

string

URL of the source article or page.

title

string

Title of the source.

source

string

Domain or publication name.

snippet

string

Relevant excerpt from the source.

relevance

string

Relationship to the post: "supporting", "refuting", or "neutral".

publishedDate

string

Publication date of the source (if available).

queriesExecuted

object[]

Search queries performed during corroboration.

Show query properties

query

string

The search query string.

sourcesFound

number

Number of sources returned for this query.

verdict

string

Overall corroboration verdict: "verified", "disputed", "inconclusive", or "insufficient_data".

summary

string

Human-readable summary of the corroboration findings.

confidenceScore

number

Confidence in the verdict from 0.0 to 1.0.

corroborationLog

string[]

Ordered list of corroboration reasoning steps as human-readable strings.

timestamp

string

required

ISO 8601 datetime when the analysis was created.

string

UUID of the completed postcard record. Use this as the {id} parameter for the OG image endpoint.

{
  "status": "completed",
  "url": "https://x.com/user/status/123",
  "platform": "X",
  "postcardScore": 0.875,
  "markdown": "# Post content...",
  "postcard": {
    "platform": "X",
    "mainText": "Post content here...",
    "username": "@username",
    "timestampText": "2h ago"
  },
  "triangulation": {
    "targetUrl": "https://x.com/user/status/123",
    "queries": []
  },
  "audit": {
    "originScore": 0.85,
    "temporalScore": 0.9,
    "totalScore": 0.875,
    "auditLog": []
  },
  "corroboration": {
    "primarySources": [],
    "queriesExecuted": [],
    "verdict": "verified",
    "summary": "Content has been corroborated by trusted sources.",
    "confidenceScore": 0.85,
    "corroborationLog": []
  },
  "timestamp": "2026-04-04T12:00:00.000Z",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Failed (status: “failed”)

The analysis could not be completed. The error field contains a description of what went wrong.

status

string

required

"failed".

string

UUID of the failed postcard record.

error

string

Description of the failure (e.g., "Unable to access this content. Login or signup wall detected.").

{
  "status": "failed",
  "error": "Unable to access this content. Login or signup wall detected."
}

Not found (404)

No analysis exists for the given URL. Submit the URL via POST /api/postcards to start a trace.

status

string

required

"not_found".

error

string

required

Human-readable message directing the caller to submit the URL.

{
  "status": "not_found",
  "error": "Analysis not found. Submit this URL via the Postcard UI to start a trace."
}

Polling pattern

Poll this endpoint every 3–5 seconds after submitting a URL. Stop when status is "completed" or "failed".

# Step 1: start analysis
JOB=$(curl -s -X POST "https://postcard.fartlabs.org/api/postcards" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://x.com/user/status/123" }' | jq -r '.id')

# Step 2: poll for completion
while true; do
  RESPONSE=$(curl -s "https://postcard.fartlabs.org/api/postcards?url=https://x.com/user/status/123")
  STATUS=$(echo "$RESPONSE" | jq -r '.status')

  if [ "$STATUS" = "completed" ]; then
    echo "$RESPONSE" | jq '.postcard'
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Error: $(echo "$RESPONSE" | jq -r '.error')"
    break
  fi

  echo "Progress: $(echo "$RESPONSE" | jq -r '.progress // 0')"
  sleep 3
done

Overview

Endpoints

Get postcard status

Request

Query parameters

Responses

Processing (status: “processing”)

Completed (status: “completed”)

Failed (status: “failed”)

Not found (404)

Polling pattern

Build docs developers (and LLMs) love

Overview

Endpoints

​Request

​Query parameters

​Responses

​Processing (status: “processing”)

​Completed (status: “completed”)

​Failed (status: “failed”)

​Not found (404)

​Polling pattern

Build docs developers (and LLMs) love

Request

Query parameters

Responses

Processing (status: “processing”)

Completed (status: “completed”)

Failed (status: “failed”)

Not found (404)

Polling pattern