---
title: "Poll many jobs in one call (≤100 ids)"
method: POST
path: "/jobs/bulk-status"
---

# Poll many jobs in one call (≤100 ids)

`POST /jobs/bulk-status`

## Request

- Base URL: `https://creatorscore.io/api/v1`
- URL: `https://creatorscore.io/api/v1/jobs/bulk-status`
- Auth: API key in header `X-API-Key`

## Request body

- object
  - `job_ids` string[], required
  - `include` string: Same options as ?include= on GET /jobs/{job_id}; comma-separated. Free.

## Response `200`

Always 200; per-job statuses are nested.

- object
  - `jobs` JobStatus[]
    - union
      - object: In-flight job
        - `job_id` string, uuid
        - `status` 'queued' | 'processing'
        - `progress` integer
        - `progress_message` string, nullable
        - `eta_seconds` integer
        - `created_at` string, date-time
      - object: Completed job
        - `job_id` string, uuid
        - `status` 'done'
        - `progress` 100
        - `completed_at` string, date-time
        - `creator` Creator
          - `platform` 'tiktok' | 'instagram' | 'youtube' | 'twitter' | 'x' | 'facebook' | 'reddit' | 'twitch' | 'kick' | 'linkedin' | 'threads' | 'snapchat', required
          - `handle` string, required
          - `display_name` string, nullable
          - `followers` integer, nullable
          - `score` integer, required: The creator's CreatorScore — their WHOLE cross-platform footprint, not just the account named by platform/handle. A CreatorScore is a person, not an account. Falls back to this account's own score only when the creator has no linked footprint yet (see score_scope).
          - `tier` string, nullable: Human-readable tier label for `score` (the footprint).
          - `platform_score` integer, nullable: This ACCOUNT's own score — the per-account building block the footprint is assembled from. Supporting detail; not the creator's CreatorScore.
          - `platform_tier` string, nullable: Tier label for `platform_score`.
          - `score_scope` 'footprint' | 'account', required: Whether `score` is the unified cross-platform footprint (normal) or an account-level fallback because the creator has no linked footprint yet.
          - `agents` AgentScores, required
            - `content_risk` number, nullable, required
            - `brand_safety` number, nullable, required
            - `sentiment` number, nullable, required
            - `authenticity` number, nullable, required
            - `audience_quality` number, nullable, required
            - `community_trust` number, nullable, required
            - `roi_prediction` number, nullable, required
          - `knockouts` Knockout[], required
            - `flag` string, required
            - `reason` string, required
          - `last_scored_at` string, date-time, required
          - `public_profile_url` string, uri, required
        - `report_url` string: Relative URL of the full evidence report for this creator (GET /creators/{platform}/{handle}/report). Included in the credit for the tenant that scored them.
        - `report` object: Present when include=report: the full report object (see /report).
        - `identity_group_id` string, nullable: Footprint jobs only.
        - `unified_score` integer, nullable: Footprint jobs only: the official unified cross-platform CreatorScore.
        - `unified_source` 'monitored_identity_group' | 'estimated_follower_weighted' | 'null', nullable
        - `accounts` object[]: Footprint jobs only: per-account breakdown (supporting detail under the unified headline).
          - `platform` string
          - `handle` string
          - `score` integer, nullable
          - `tier` string, nullable
          - `followers` integer, nullable
      - object: Failed job
        - `job_id` string, uuid
        - `status` 'failed'
        - `progress` integer
        - `error` string
        - `failed_at` string, date-time, nullable
      - object: Unknown job
        - `job_id` string, uuid
        - `status` 'not_found'
        - `message` string
  - `summary` object
    - `total` integer
    - `done` integer
    - `in_flight` integer
    - `failed` integer
    - `not_found` integer

## Other responses

- `401`: Missing or invalid API key.
- `429`: Per-key rate limit hit (120 req/min). Retry after the duration in the Retry-After header.

---

[API](https://skmtc.dev/creatorscore/apis/creatorscore-api.md) · [All operations](https://skmtc.dev/creatorscore/apis/creatorscore-api/llms.txt) · [OpenAPI document](https://skmtc.dev/creatorscore/apis/creatorscore-api/revisions/d3a219842277?raw)