---
title: "Get Tool Jobs Status Batch"
method: POST
path: "/api/tool-jobs/status-batch"
tags: ["growth-artifact-jobs"]
---

# Get Tool Jobs Status Batch

`POST /api/tool-jobs/status-batch`

## Request

- Base URL: `https://platform.verbiflow.com/api/bridge`
- URL: `https://platform.verbiflow.com/api/bridge/api/tool-jobs/status-batch`
- Auth: one of:
  - HTTP bearer and API key in header `x-flage-org-id`
  - HTTP bearer and API key in header `x-flage-org-slug`

## Request body

- ToolJobStatusBatchRequest
  - `job_ids` string[], required

## Response `200`

Successful Response

- ToolJobStatusBatchResponse
  - `jobs` ToolJobResponse[], required: Readable jobs in request order.
    - `artifact_id` string, nullable, required: Immutable result artifact when it is readable.
    - `error_message` string, nullable, required: Terminal public failure detail, or null.
    - `failed` boolean, required: True when the durable status is failed.
    - `finished` boolean, required: True after a durable terminal event exists.
    - `job_id` string, required: Durable job identity.
    - `limit` integer, required: Maximum preview rows requested.
    - `offset` integer, required: Zero-based preview row offset.
    - `phase` string, required: Current producer-defined execution phase.
    - `progress_current` integer, required: Durably completed work units.
    - `progress_total` integer, required: Declared work units for this execution.
    - `rows` ArtifactJobRow[], required: Bounded business-row preview; read the artifact for complete rows and evidence.
      - union: A tool-specific result row or another complete dynamic artifact row.
        - GeoClassificationResultRow: Geo fields appended to the caller's complete input row.
          - `geo_classification_error` string, required: Empty on success; bounded per-row failure detail otherwise.
          - `geo_classification_reason` string, required: Resolver explanation for the containment verdict.
          - `geo_credit_units` string, required: Exact nonnegative decimal customer-credit usage for this row.
          - `geo_resolved_level` 'metro' | 'city' | 'admin1' | 'country' | 'ambiguous' | 'unknown', required
        - AiAnalysisResultRow: Fixed audit fields plus every caller input and output_schema-defined field.
          - `ai_enrichment_error` string, required: Empty on success; bounded per-row provider or validation failure.
          - `model_used` string, required: Successful model, or the final attempted model when the row failed.
        - PlaceSearchResultRow: One normalized physical place with the query and rank that found it.
          - `address` string, required: Provider street or formatted address, or empty.
          - `category` string, required: Provider place category, or empty.
          - `city` string, required: Provider city, or empty when unavailable.
          - `country` string, required: Provider country code or name, or empty.
          - `google_maps_url` string, required: Provider map listing URL, or empty.
          - `lat` union, required: Observed latitude, including zero.
            - integer
            - number
          - `lng` union, required: Observed longitude, including zero.
            - integer
            - number
          - `name` string, required: Provider place or business name, or empty if absent.
          - `phone` string, required: Provider phone representation, or empty.
          - `place_id` string, required: Provider physical-place identity, or empty if absent.
          - `query` string, required: Exact normalized query that produced this row.
          - `rank` integer, required: One-based rank within the producing query.
          - `rating` union, required: Observed aggregate rating, including zero.
            - integer
            - number
          - `reviews_count` integer, nullable, required: Observed review count, including zero.
          - `state` string, required: Provider state or first-level region, or empty.
          - `website` string, required: Provider website URL, or empty.
        - PlaceReviewResultRow: One normalized review linked to the physical place requested by the caller.
          - `likes_count` integer, nullable, required: Observed helpful-like count, including zero.
          - `place_id` string, required: Physical-place identity this review belongs to.
          - `published_at` string, required: Provider publication timestamp or date representation, or empty.
          - `rating` union, required: Review rating, including zero.
            - integer
            - number
          - `response_text` string, required: Place-owner response text, or empty when unavailable.
          - `review_id` string, required: Provider review identity, or empty if absent.
          - `reviewer_name` string, required: Provider reviewer display name, or empty.
          - `text` string, required: Review text, or empty when unavailable.
        - ArtifactBusinessRow: Complete dynamic business row stored in the artifact.
    - `status` 'queued' | 'running' | 'blocked' | 'completed' | 'failed', required: Durable job lifecycle status.
    - `summary` union, required: Sanitized job progress with typed fields for known producer families.
      - GeoClassificationJobSummary: Known public progress fields for rows.geo_classify, preserving extensions.
        - `accepted_pricing` AcceptedJobPricing: Immutable rule used to rate this job; final usage determines the actual charge.
          - `basis` 'none' | 'successful_execution' | 'successful_provider_attempt' | 'requested_record' | 'delivered_record' | 'successful_record' | 'provider_unit' | 'provider_cost_usd' | 'resolver_reported', required
          - `billing_owner` 'none' | 'growth_capability' | 'source_execution' | 'enrichment_reservation', required
          - `credits_per_unit` string, required: Exact Decimal customer-credit rate per unit, encoded as a string. This is not the final charge.
          - `pricing_version` string, required: Immutable published rate-book revision captured when the job was admitted.
          - `unit` string, required: Unit counted by basis, such as a record or execution.
        - `actual_credit_units` string: Exact Decimal total customer-credit usage for this chunk.
        - `artifact_id` string: Immutable result artifact identity.
        - `capability_id` 'rows.geo_classify': Metered SDK capability identity.
        - `chunk` GeoClassificationChunkSummary
          - `max_rows` integer, required: Maximum rows admitted for this chunk.
          - `next_start_row` integer, nullable, required: One-based first row of the next chunk, or null when complete.
          - `remaining_rows` integer, required: Source rows after this chunk.
          - `row_count` integer, required: Rows admitted in this chunk.
          - `start_row` integer, required: One-based first source row in this chunk.
          - `total_rows` integer, required: Rows in the complete source input.
        - `columns` string[]: Complete result CSV column order.
        - `completeness` 'complete' | 'partial': Complete when no row failed; partial when at least one row failed.
        - `error_rows` integer: Rows with a classification error.
        - `execution_contract_digest` string: Digest of the executable operation contract.
        - `generation_id` string: Immutable durable generation identity.
        - `input_artifact_id` string: Immutable uploaded source artifact.
        - `next_start_row` integer, nullable: One-based first row of the next chunk, or null when complete.
        - `operation_key` string: Durable logical operation identity.
        - `output_column` string: Caller-selected verdict column name.
        - `output_columns` string[]: Columns appended by geo classification.
        - `processed_rows` integer: Rows processed by the worker.
        - `remaining_rows` integer: Source rows after this job chunk.
        - `result_kind` 'geo_classification': Typed terminal result discriminator.
        - `result_manifest_digest` string: Digest of the complete immutable result rows.
        - `row_count` integer: Rows admitted in this job chunk.
        - `semantic_fingerprint` string: Digest of the operation semantics used for this generation.
        - `source_digest` string: Digest of the immutable source input when available.
        - `start_row` integer: One-based first source row in this job chunk.
        - `target` string: Requested geography containment target.
        - `text_columns` string[], nullable: Input columns used to assemble each location string.
        - `tool_kind` 'geo_classify_rows': Geo worker discriminator.
        - `total_rows` integer: Rows in the complete source input.
        - `upload_id` string: Source CSV upload identity.
      - AiAnalysisJobSummary: Complete public admission, progress, and terminal rows.ai_analyze summary.
        - `accepted_pricing` AcceptedJobPricing: Immutable rule used to rate this job; final usage determines the actual charge.
          - `basis` 'none' | 'successful_execution' | 'successful_provider_attempt' | 'requested_record' | 'delivered_record' | 'successful_record' | 'provider_unit' | 'provider_cost_usd' | 'resolver_reported', required
          - `billing_owner` 'none' | 'growth_capability' | 'source_execution' | 'enrichment_reservation', required
          - `credits_per_unit` string, required: Exact Decimal customer-credit rate per unit, encoded as a string. This is not the final charge.
          - `pricing_version` string, required: Immutable published rate-book revision captured when the job was admitted.
          - `unit` string, required: Unit counted by basis, such as a record or execution.
        - `accounting_started_at` string: UTC accounting-admission timestamp.
        - `agent` AiAnalysisAgentSummary: Bounded immutable-evidence agent policy admitted for each row.
          - `kind` 'agent', required: Agent execution discriminator.
          - `max_tool_calls` integer, required: Maximum combined immutable-evidence search and read calls per row.
        - `analysis_execution` 'direct' | 'agent': Direct sends the projected row once; agent can search and read immutable evidence files within a bounded tool budget.
        - `artifact_id` string, nullable: Immutable result artifact identity when available.
        - `capability_id` 'rows.ai_enrich': Metered capability identity.
        - `chunk` AiAnalysisChunkSummary: Exact source partition coordinates for one AI analysis job.
          - `max_rows` integer: Maximum rows admitted for this chunk.
          - `next_start_row` integer, nullable: One-based first row of the next chunk, or null when complete.
          - `remaining_rows` integer: Source rows after this chunk.
          - `row_count` integer: Rows admitted in this chunk.
          - `start_row` integer: One-based first source row in this chunk.
          - `total_rows` integer: Rows in the complete source input.
        - `columns` string[]: Input column order during progress and complete result column order at terminal.
        - `completeness` 'complete' | 'partial': Complete when no row failed; partial when at least one row failed.
        - `error` integer: Rows ending with ai_enrichment_error.
        - `execution_contract_digest` string: Digest of the executable analysis contract.
        - `generation_id` string: Immutable durable generation identity.
        - `input_artifact_id` string, nullable: Immutable staged source artifact identity.
        - `input_format` 'csv' | 'artifact_json_v1': Encoding of the staged input.
        - `materializer_operation_id` 'rows.ai_analyze': Reviewed artifact materializer operation identity.
        - `materializer_operation_version` 'v1': Reviewed artifact materializer operation version.
        - `mode` 'medium' | 'max': Effective server model-quality tier alias.
        - `model` string: Primary model selected for this job execution.
        - `model_input_fields` string[], nullable: Exact source columns made available to the model, or null before the worker resolves the canonical projection.
        - `model_pool` string[]: Ordered server-selected fallback model pool.
        - `next_start_row` integer, nullable: One-based first row of the next chunk, or null when complete.
        - `operation_key` string: Durable logical operation identity.
        - `output_columns` string[]: Caller-defined columns generated from output_schema.
        - `play_id` string, nullable: Owning durable Play identity when admission came from a Play.
        - `processed_rows` integer: Rows with a durable result.
        - `provider_usage` AiAnalysisProviderUsage: Bounded aggregate of physical model attempts for a terminal AI analysis job.
          - `cached_input_tokens` integer, required: Cached input tokens across all attempts.
          - `has_unknown_provider_cost` boolean, required: True when at least one physical attempt has no known provider cost.
          - `input_tokens` integer, required: Uncached input tokens across all attempts.
          - `known_provider_cost_usd` string, required: Exact sum of the provider costs that were known.
          - `models` string[], required: Sorted distinct requested or responding model identifiers.
          - `output_tokens` integer, required: Non-reasoning output tokens across all attempts.
          - `pricing_versions` string[], required: Sorted distinct provider rate-card versions observed.
          - `provider_attempts` integer, required: Completed physical model attempts, including retries.
          - `provider_cost_usd` string, nullable, required: Exact total provider cost in USD, or null when any attempt lacks known cost.
          - `provider_failed_attempts` integer, required: Physical model attempts that returned a failure.
          - `provider_retries` integer, required: Physical attempts after the first attempt for each row.
          - `reasoning_tokens` integer, required: Reasoning tokens across all attempts.
        - `remaining_rows` integer: Source rows after this job chunk.
        - `request_digest` string: Digest of the admitted public request.
        - `result_kind` 'row_analysis': Typed terminal result discriminator.
        - `result_manifest_digest` string: Digest of the complete immutable result rows.
        - `row_count` integer: Rows admitted in this job chunk.
        - `sdk_artifact_binding_version` 1: Artifact-to-SDK binding format version.
        - `semantic_fingerprint` string: Digest of the analysis semantics used for this generation.
        - `source_digest` string: Digest of the immutable source input when available.
        - `start_http_status` integer: HTTP status recorded at durable admission.
        - `start_row` integer: One-based first source row in this job chunk.
        - `submission_id` string, nullable: Caller submission identity, or null for legacy admission.
        - `succeeded` integer: Rows whose generated output passed validation.
        - `tier` 'medium' | 'max': Effective server model-quality tier.
        - `tool_kind` 'ai_enrich_rows': AI analysis worker discriminator.
        - `total_rows` integer: Rows in the complete caller input.
        - `upload_id` string, nullable: Staged input upload identity.
        - `workload` 'analysis' | 'writing' | 'evaluation': Effective model workload policy.
      - PlacesSearchJobSummary: Known durable progress and terminal fields for a places-search job.
        - `accepted_pricing` union: Immutable customer-credit rule accepted at admission.
          - AcceptedJobPricing: Immutable rule used to rate this job; final usage determines the actual charge.
            - `basis` 'none' | 'successful_execution' | 'successful_provider_attempt' | 'requested_record' | 'delivered_record' | 'successful_record' | 'provider_unit' | 'provider_cost_usd' | 'resolver_reported', required
            - `billing_owner` 'none' | 'growth_capability' | 'source_execution' | 'enrichment_reservation', required
            - `credits_per_unit` string, required: Exact Decimal customer-credit rate per unit, encoded as a string. This is not the final charge.
            - `pricing_version` string, required: Immutable published rate-book revision captured when the job was admitted.
            - `unit` string, required: Unit counted by basis, such as a record or execution.
          - UnavailablePlacesJobPricing: Empty historical receipt when a legacy worker had no admitted pricing snapshot.
        - `accounting_started_at` string: UTC accounting admission timestamp.
        - `artifact_id` string: Immutable result artifact identity.
        - `cancel_reason` string: Bounded durable cancellation reason.
        - `cancelled` boolean: Whether processing was durably cancelled.
        - `capability_id` 'places.search': Metered capability.
        - `columns` string[]: Committed artifact column order.
        - `committed_batch_count` integer: Durable artifact batches committed.
        - `completeness` 'complete' | 'capped': Complete or caller-capped result.
        - `error` string, nullable: Bounded terminal failure detail, or null after recovery.
        - `execution_contract_digest` string: Digest of the executable contract.
        - `generation_id` string: Immutable result generation identity.
        - `limit` integer: Maximum rows requested.
        - `location` string, nullable: Normalized location hint, or null.
        - `materialized_partition_count` integer: Query partitions used.
        - `materialized_partitions_reused` integer: Query partitions recovered without another provider call.
        - `materializer_activity_timeout_seconds` integer: Maximum worker activity runtime in seconds.
        - `materializer_no_progress_timeout_seconds` integer: Maximum interval without partition progress in seconds.
        - `materializer_operation_id` string: Reviewed materializer operation identity.
        - `materializer_operation_version` string: Reviewed materializer operation version.
        - `operation_key` string: Durable logical operation identity.
        - `play_id` string, nullable: Owning durable Play identity, or null.
        - `query_count` integer: Number of admitted queries.
        - `recovery_committed_row_count` integer: Rows retained from the failed generation.
        - `recovery_held_partition_count` integer: Held provider partitions adopted for recovery.
        - `recovery_ordinal` integer: One-based recovery attempt ordinal.
        - `recovery_parent_execution_id` string: Prior failed accounting execution recovered by this run.
        - `replayed` boolean: Whether admission reused the durable generation.
        - `request_digest` string: Digest of the canonical public request.
        - `requested_units` integer: Customer-credit units reserved.
        - `result_kind` 'places_search': Terminal result discriminator.
        - `result_manifest_digest` string: Digest of committed rows and coverage.
        - `row_count` integer: Rows committed to the artifact.
        - `sdk_artifact_binding_version` 1: Artifact SDK binding format version.
        - `semantic_fingerprint` string: Digest of the request semantics.
        - `source_digest` string: Managed source digest when provided.
        - `start_http_status` integer: HTTP status recorded at admission.
        - `temporal_workflow_id` string: Durable worker workflow identity during recovery.
        - `termination` 'provider_exhausted' | 'request_limit_reached': Whether the provider exhausted or the caller row limit stopped collection.
        - `tool_kind` 'places_search': Worker discriminator.
      - PlacesReviewsJobSummary: Known durable progress and terminal fields for a places-review job.
        - `accepted_pricing` union: Immutable customer-credit rule accepted at admission.
          - AcceptedJobPricing: Immutable rule used to rate this job; final usage determines the actual charge.
            - `basis` 'none' | 'successful_execution' | 'successful_provider_attempt' | 'requested_record' | 'delivered_record' | 'successful_record' | 'provider_unit' | 'provider_cost_usd' | 'resolver_reported', required
            - `billing_owner` 'none' | 'growth_capability' | 'source_execution' | 'enrichment_reservation', required
            - `credits_per_unit` string, required: Exact Decimal customer-credit rate per unit, encoded as a string. This is not the final charge.
            - `pricing_version` string, required: Immutable published rate-book revision captured when the job was admitted.
            - `unit` string, required: Unit counted by basis, such as a record or execution.
          - UnavailablePlacesJobPricing: Empty historical receipt when a legacy worker had no admitted pricing snapshot.
        - `accounting_started_at` string: UTC accounting admission timestamp.
        - `artifact_id` string: Immutable result artifact identity.
        - `cancel_reason` string: Bounded durable cancellation reason.
        - `cancelled` boolean: Whether processing was durably cancelled.
        - `capability_id` 'places.reviews': Metered capability.
        - `columns` string[]: Committed artifact column order.
        - `committed_batch_count` integer: Durable artifact batches committed.
        - `completeness` 'complete' | 'capped': Complete or caller-capped result.
        - `error` string, nullable: Bounded terminal failure detail, or null after recovery.
        - `execution_contract_digest` string: Digest of the executable contract.
        - `generation_id` string: Immutable result generation identity.
        - `materialized_partition_count` integer: Place partitions used.
        - `materialized_partitions_reused` integer: Place partitions recovered without another provider call.
        - `materializer_activity_timeout_seconds` integer: Maximum worker activity runtime in seconds.
        - `materializer_no_progress_timeout_seconds` integer: Maximum interval without partition progress in seconds.
        - `materializer_operation_id` string: Reviewed materializer operation identity.
        - `materializer_operation_version` string: Reviewed materializer operation version.
        - `max_reviews` integer: Maximum reviews per place.
        - `operation_key` string: Durable logical operation identity.
        - `place_count` integer: Number of admitted physical place ids.
        - `play_id` string, nullable: Owning durable Play identity, or null.
        - `recovery_committed_row_count` integer: Rows retained from the failed generation.
        - `recovery_held_partition_count` integer: Held provider partitions adopted for recovery.
        - `recovery_ordinal` integer: One-based recovery attempt ordinal.
        - `recovery_parent_execution_id` string: Prior failed accounting execution recovered by this run.
        - `replayed` boolean: Whether admission reused the durable generation.
        - `request_digest` string: Digest of the canonical public request.
        - `requested_units` integer: Customer-credit units reserved.
        - `result_kind` 'places_reviews': Terminal result discriminator.
        - `result_manifest_digest` string: Digest of committed rows and coverage.
        - `row_count` integer: Review rows committed to the artifact.
        - `sdk_artifact_binding_version` 1: Artifact SDK binding format version.
        - `semantic_fingerprint` string: Digest of the request semantics.
        - `since` string, nullable: Normalized lower publication-date bound, or null.
        - `source_digest` string: Managed source digest when provided.
        - `start_http_status` integer: HTTP status recorded at admission.
        - `temporal_workflow_id` string: Durable worker workflow identity during recovery.
        - `termination` 'provider_exhausted' | 'request_limit_reached': Whether providers exhausted or a per-place review bound was reached.
        - `tool_kind` 'places_reviews': Worker discriminator.
      - ArtifactPublicMetadata: Sanitized producer metadata. Keys vary by tool kind; secret and private storage-coordinate keys are removed recursively.
    - `tool_kind` string, required: Server-owned worker kind that produced this job.
  - `missing_job_ids` string[], required: Requested identities that were absent or outside the organization.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract.md) - [All operations](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/llms.txt) - [OpenAPI document](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/revisions/c80e903ef8f3?raw)