Verification Runs API

A verification run executes one pipeline against a set of files and optional context data. The run progresses through one or more stages — AI analysis, crowd review, or both — and produces a final verdict with confidence score and scorecard.

Endpoint Reference

Method	Path	Description
`POST`	`/v2/projects/{projectId}/verification-runs`	Start a verification run
`GET`	`/v2/projects/{projectId}/verification-runs`	List runs
`GET`	`/v2/projects/{projectId}/verification-runs/{runId}`	Get run with stage detail

Start a Verification Run

POST /v2/projects/{projectId}/verification-runs

Request body

Field	Type	Required	Description
`pipeline_id`	string	Yes	Pipeline slug, e.g. `"verify-image-metadata"`
`file_ids`	string[]	Depends	IDs of files to include; required by most pipelines
`context_id`	string	Depends	ID of a saved verification context
`context`	object	Depends	Inline context key-value pairs (not saved)

Context requirements vary by pipeline. Check the pipeline's requiredContextKeys before starting a run. See Pipelines for the full catalog.

curl -X POST https://api.crowdee.ai/v2/projects/proj_abc123/verification-runs \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "verify-news-article",
    "file_ids": ["file_xyz789"],
    "context": {
      "claimed_source_url": "https://example.com/article-123",
      "claimed_publication_date": "2024-10-28",
      "claimed_author": "Jane Doe"
    }
  }'

Response

{
  "id": "run_def456",
  "projectId": "proj_abc123",
  "pipelineId": "verify-news-article",
  "status": "running",
  "fileIds": ["file_xyz789"],
  "createdAt": "2024-11-15T10:02:00Z"
}

Save the id — you will poll it to retrieve the verdict.

Run Status Values

Status	Meaning
`pending`	Run created, queued for execution
`running`	Stages currently executing
`awaiting_crowd`	Waiting for crowd stage responses (Tier 2/3 pipelines only)
`completed`	All stages done; verdict available
`failed`	One or more stages errored; check the `error` field

Get a Run

GET /v2/projects/{projectId}/verification-runs/{runId}

Returns the full run object including individual stage results once the run reaches completed status.

curl https://api.crowdee.ai/v2/projects/proj_abc123/verification-runs/run_def456 \
  -H "X-API-Key: crw_YOUR_API_KEY"

Response — in progress

{
  "id": "run_def456",
  "pipelineId": "verify-news-article",
  "status": "running",
  "fileIds": ["file_xyz789"],
  "stages": [
    {
      "slug": "source-credibility",
      "type": "ai",
      "order": 1,
      "status": "completed",
      "verdict": "authentic",
      "confidence": 88,
      "summary": "Source domain has strong credibility signals and consistent publication history."
    },
    {
      "slug": "content-coherence",
      "type": "ai",
      "order": 2,
      "status": "running",
      "verdict": null,
      "confidence": null,
      "summary": null
    }
  ],
  "createdAt": "2024-11-15T10:02:00Z"
}

Response — completed

{
  "id": "run_def456",
  "pipelineId": "verify-news-article",
  "status": "completed",
  "verdict": "authentic",
  "confidence": 87,
  "scorecard": {
    "source_credibility": 88,
    "content_coherence": 91,
    "fact_consistency": 82,
    "crowd_validation": 85
  },
  "explanation": "The article's claims are consistent with identified primary sources. The publication date and byline match public records. Crowd reviewers confirmed factual accuracy with high confidence.",
  "report": "...",
  "fileIds": ["file_xyz789"],
  "stages": [
    {
      "slug": "source-credibility",
      "type": "ai",
      "order": 1,
      "status": "completed",
      "verdict": "authentic",
      "confidence": 88,
      "summary": "Source domain has strong credibility signals and consistent publication history."
    },
    {
      "slug": "content-coherence",
      "type": "ai",
      "order": 2,
      "status": "completed",
      "verdict": "authentic",
      "confidence": 91,
      "summary": "Internal narrative is consistent. No contradictions found between headline, body, and cited sources."
    },
    {
      "slug": "crowd-fact-check",
      "type": "crowd",
      "order": 3,
      "status": "completed",
      "verdict": "authentic",
      "confidence": 85,
      "summary": "12 crowd reviewers reached consensus: claims verified against 4 independent sources."
    }
  ],
  "createdAt": "2024-11-15T10:02:00Z",
  "completedAt": "2024-11-15T11:15:22Z"
}

Possible verdict values: authentic, manipulated, inconclusive, unverified

Polling for Completion

Poll GET /v2/projects/{projectId}/verification-runs/{runId} until status is completed or failed.

Pipeline tier	Poll interval
Tier 1 (AI-only)	Every 5–10 seconds
Tier 2 (AI + Crowd)	Every 30–60 seconds
Tier 3 (Context / multi-file)	Every 10–60 seconds

For Tier 2 pipelines, the run may stay in awaiting_crowd for extended periods while crowd workers complete their review tasks. Implement idempotent polling and consider running it as a background job rather than blocking a synchronous request. Crowd stages typically complete within 1–4 hours, depending on task complexity and available workers.

# Keep polling until status is completed or failed
while true; do
  RESPONSE=$(curl -s https://api.crowdee.ai/v2/projects/proj_abc123/verification-runs/run_def456 \
    -H "X-API-Key: crw_YOUR_API_KEY")
  STATUS=$(echo $RESPONSE | jq -r '.status')
  echo "Status: $STATUS"
  if [[ "$STATUS" == "completed" || "$STATUS" == "failed" ]]; then
    echo $RESPONSE | jq .
    break
  fi
  sleep 10
done

Listing Runs

GET /v2/projects/{projectId}/verification-runs

Query parameters

Parameter	Type	Description
`status`	string	Filter by run status
`pipeline_id`	string	Filter by pipeline slug
`limit`	integer	Default 20, max 200
`offset`	integer	Default 0

# List completed runs for a specific pipeline
curl "https://api.crowdee.ai/v2/projects/proj_abc123/verification-runs?status=completed&pipeline_id=verify-image-metadata&limit=20" \
  -H "X-API-Key: crw_YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "run_def456",
      "pipelineId": "verify-image-metadata",
      "status": "completed",
      "verdict": "authentic",
      "confidence": 92,
      "createdAt": "2024-11-15T10:02:00Z",
      "completedAt": "2024-11-15T10:02:18Z"
    },
    {
      "id": "run_ghi789",
      "pipelineId": "verify-image-metadata",
      "status": "completed",
      "verdict": "manipulated",
      "confidence": 96,
      "createdAt": "2024-11-14T08:45:00Z",
      "completedAt": "2024-11-14T08:45:31Z"
    }
  ],
  "total": 8,
  "limit": 20,
  "offset": 0
}

On this page