---
title: "Get Tool Job"
method: GET
path: "/api/tool-jobs/{job_id}"
tags: ["growth-artifact-jobs"]
---

# Get Tool Job

`GET /api/tool-jobs/{job_id}`

## Request

- Base URL: `https://platform.verbiflow.com/api/bridge`
- URL: `https://platform.verbiflow.com/api/bridge/api/tool-jobs/{job_id}`
- 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`

## Path parameters

- `job_id` string, required

## Query parameters

- `offset` integer
- `limit` integer
- `include_rows_if_terminal` boolean

## Response `200`

Successful Response

- ToolJobResponse
  - `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.

## 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)