Crowd Jobs

Ein Crowd Job ist eine eigenständige Crowdsourcing-Kampagne, die einem Projekt zugeordnet ist. Er verknüpft eine veröffentlichte Survey-Template-Version mit einem optionalen Input-Data-Set und stellt strukturierte Aufgaben für den Worker-Pool von Crowdee bereit. Worker beanspruchen einzelne Aufgaben-Slots, füllen den strukturierten Fragebogen aus und reichen ihre Antworten ein. Sie prüfen jede Einreichung und akzeptieren oder lehnen sie ab — bei akzeptierten Antworten werden die reservierten Credits an den Worker freigegeben.

Crowd Jobs sind unabhängig von Verifizierungs-Pipelines. Während Crowd-Stages in Pipelines automatisch durch den Pipeline-Runner ausgelöst werden, geben Crowd Jobs Ihnen direkte Kontrolle: Sie definieren die Aufgabe, legen das Verfügbarkeitsfenster und die Vergütung fest und verwalten den Lebenszyklus über die API oder die Plattform-UI.

Job-Felder

Beim Erstellen oder Aktualisieren eines Crowd Jobs werden folgende Felder akzeptiert.

Job-Status-Lebenszyklus

Ein Job durchläuft folgende Status, wenn sich die Bedingungen ändern. Das Feld computedStatus, das von GET /v2/crowd-jobs/:jobId zurückgegeben wird, spiegelt den aktuellen Zustand wider, der bei jedem Abruf neu berechnet wird; das gespeicherte Feld status wird verzögert aktualisiert, um den berechneten Status widerzuspiegeln.

Einen Job erstellen

Jobs werden einem Projekt zugeordnet angelegt. Die mindestens erforderlichen Felder sind name, title, description und surveyTemplateVersionId.

curl -X POST https://api.crowdee.ai/v2/projects/{projectId}/crowd-jobs \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 Image Authenticity Review",
    "title": "Assess whether this image has been digitally manipulated",
    "description": "You will be shown an image and asked to provide your expert assessment. Please review all visible evidence carefully before submitting.",
    "category": "survey",
    "surveyTemplateVersionId": "tmplv_abc123def456ghi789jkl01",
    "inputDataSetId": "idata_xyz987stu654rqp321onm09",
    "maxRepetitionsPerVariant": 3,
    "rewardCredits": 25,
    "validFrom": "2026-07-01T08:00:00Z",
    "validUntil": "2026-07-31T18:00:00Z",
    "forceUniqueTasks": true
  }'

Eine 201 Created-Response gibt das vollständige Job-Objekt zurück, einschließlich der systemseitig vergebenen id, der berechneten creditsBlocked und eines dryRunMagicToken, falls isDryRun auf true gesetzt war.

Dry Runs

Ein Dry Run ermöglicht es Ihnen, das vollständige Worker-Erlebnis zu testen — Aufgaben-Rendering, Survey-Anzeige, Antworteinreichung — ohne Credits zu blockieren oder den Job dem gesamten Worker-Pool zugänglich zu machen.

Setzen Sie beim Erstellen des Jobs isDryRun: true. Die Plattform wird:

• Keine Credits von Ihrem Organisationsguthaben blockieren.
• Einen eindeutigen dryRunMagicToken generieren (eine kurze zufällige Zeichenkette, die in der Job-Response zurückgegeben wird).
• Den Aufgabenzugriff auf Worker beschränken, deren registrierte E-Mail-Adresse in dryRunAllowedEmails enthalten ist, oder auf alle Personen, die auf den Job über den Magic-Token-Link in der Worker-UI zugreifen.

Ein Magic-Token-Link hat die Form https://workers.crowdee.ai/jobs/{jobId}?token={dryRunMagicToken}. Teilen Sie ihn direkt mit internen Testern, die das Worker-Erlebnis ohne Crowdee-Konto in der Vorschau sehen sollen.

{
  "name": "Q3 Image Authenticity Review — Test",
  "title": "Assess whether this image has been digitally manipulated",
  "description": "Internal preview only. Please complete as if this were a real task.",
  "category": "survey",
  "surveyTemplateVersionId": "tmplv_abc123def456ghi789jkl01",
  "isDryRun": true,
  "dryRunAllowedEmails": ["tester@yourorg.com", "qa@yourorg.com"]
}

Credits und Abrechnung

Wenn ein Nicht-Dry-Run-Job erstellt wird, reserviert Crowdee sofort Credits von Ihrem Organisationsguthaben. Der blockierte Betrag berechnet sich wie folgt:

creditsBlocked = variantCount × maxRepetitionsPerVariant × rewardCredits

Dabei entspricht variantCount der Anzahl der Datensätze im angehängten Input-Data-Set oder 1, wenn kein Input-Data-Set verwendet wird.

Credits durchlaufen im Verlauf des Job-Lebenszyklus folgende Zustände:

Wenn Sie einen Job so aktualisieren, dass die erforderliche Reservierung steigt — beispielsweise durch Erhöhung von rewardCredits oder maxRepetitionsPerVariant — werden die zusätzlichen Credits sofort von Ihrem Guthaben abgezogen. Verringerungen geben den Überschuss sofort an Ihr Guthaben zurück.

Einen Job klonen

Beim Klonen wird ein neuer Job erstellt, der die gesamte Konfiguration der Quelle übernimmt — Template-Version, Input-Data-Set, Vergütungseinstellungen, Verfügbarkeitsfenster und Zugriffssteuerungen — während Aufgaben- und Antwortverlauf zurückgesetzt werden. Der Klon startet mit status: assignable.

curl -X POST https://api.crowdee.ai/v2/crowd-jobs/{jobId}/clone \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "isDryRun": false,
    "name": "Q4 Image Authenticity Review"
  }'

Sowohl isDryRun als auch name sind optional. Wird isDryRun weggelassen, wird standardmäßig false verwendet. Wird name weggelassen, erhält der Klon den Namen {Originalname} (copy).

Typische Anwendungsfälle für das Klonen:

• Vor dem Launch testen — Klonen Sie einen bestehenden Produktions-Job mit isDryRun: true, um Template- oder Input-Data-Änderungen zu prüfen, bevor Sie Credits einsetzen.
• Eine Kampagne wiederholen — Klonen Sie einen finished-Job, um ihn mit demselben Template und Input-Data-Set erneut auszuführen, und passen Sie dabei optional das Verfügbarkeitsfenster oder die Vergütung an.
• Staging-Spiegel — Pflegen Sie eine Dry-Run-Kopie jedes Produktions-Jobs, um neue interne Prüfer einzuarbeiten, ohne Live-Daten zu berühren.

Jobs verwalten

Jobs eines Projekts auflisten — gibt standardmäßig alle nicht archivierten Jobs zurück; übergeben Sie includeArchived=true, um archivierte Jobs einzuschließen, oder status, um nach Lebenszyklusstatus zu filtern:

GET https://api.crowdee.ai/v2/projects/{projectId}/crowd-jobs?status=assignable
X-API-Key: crw_YOUR_API_KEY

Einen einzelnen Job abrufen — beinhaltet den live berechneten computedStatus und die abgeleiteten maxSlots:

GET https://api.crowdee.ai/v2/crowd-jobs/{jobId}
X-API-Key: crw_YOUR_API_KEY

computedStatus spiegelt den tatsächlichen aktuellen Zustand wider — beispielsweise not_assignable, wenn validUntil bereits abgelaufen ist, obwohl das gespeicherte Feld status noch assignable anzeigt. maxSlots entspricht variantCount × maxRepetitionsPerVariant.

Einen Job aktualisieren — jedes schreibbare Feld kann geändert werden, solange der Job nicht archiviert ist. Das Aktualisieren von rewardCredits, maxRepetitionsPerVariant oder inputDataSetId löst eine sofortige Credit-Neuberechnung und Guthabenanpassung aus:

curl -X PUT https://api.crowdee.ai/v2/crowd-jobs/{jobId} \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "validUntil": "2026-08-15T18:00:00Z",
    "maxRepetitionsPerVariant": 5
  }'

Einen Job archivieren — entspricht einem Soft-Delete. Alle aktuell zugewiesenen Aufgaben werden abgebrochen, verbleibende blockierte Credits werden an Ihr Organisationsguthaben zurückgegeben, und der Job wechselt zu archived. Diese Aktion ist nicht umkehrbar:

curl -X DELETE https://api.crowdee.ai/v2/crowd-jobs/{jobId} \
  -H "X-API-Key: crw_YOUR_API_KEY"

Job-Statistiken

Der Stats-Endpunkt liefert eine Echtzeit-Aufschlüsselung aller Aufgaben- und Antwortaktivitäten eines Jobs.

GET https://api.crowdee.ai/v2/crowd-jobs/{jobId}/stats
X-API-Key: crw_YOUR_API_KEY

Die Response enthält aggregierte Zählwerte und Worker-Detailarrays:

Das Objekt workers enthält vier Arrays, in denen individuelle Worker durch workerId (authentifizierte Worker) oder guestWorkerId (Gast-/Magic-Token-Worker) identifiziert werden:

Eine Beispiel-Response für einen Job mit 60 Gesamt-Slots, der sich mitten in einer Kampagne befindet:

{
  "maxSlots": 60,
  "currentlyWorking": 4,
  "submitted": 38,
  "accepted": 31,
  "rejected": 3,
  "pending": 4,
  "timedOut": 2,
  "cancelled": 1,
  "returned": 0,
  "workers": {
    "started": [
      { "workerId": "usr_abc", "guestWorkerId": null, "taskId": "tsk_001", "assignedAt": "2026-07-14T09:12:00Z" }
    ],
    "submitted": [...],
    "cancelled": [...],
    "timedOut": [...]
  }
}