---
title: "Start Places Search"
method: POST
path: "/api/places/search/start"
tags: ["places"]
---

# Start Places Search

`POST /api/places/search/start`

## Request

- Base URL: `https://platform.verbiflow.com/api/bridge`
- URL: `https://platform.verbiflow.com/api/bridge/api/places/search/start`
- 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

- PlacesSearchStartRequest
  - `contract_version` 'places-search.v2', required
  - `limit` integer: Maximum places returned across all queries.
  - `location` string, nullable: Optional provider location hint; whitespace-only values are omitted.
  - `queries` string[], required: Provider-neutral place queries; values are stripped and empty values rejected.

## Response `202`

Successful Response

- PlacesSearchJobStartResponse: Durable admission receipt for physical-place search.
  - `accepted_pricing` AcceptedJobPricing, required: 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.
  - `artifact_id` string, required: Immutable result artifact identity.
  - `execution_contract_digest` string, required: Digest of the executable operation contract.
  - `execution_id` string, required: Customer-credit accounting execution identity.
  - `failed` boolean, required: Whether the terminal state is failed.
  - `finished` boolean, required: Whether the job reached a terminal state.
  - `generation_id` string, required: Immutable durable generation identity.
  - `job_id` string, required: Durable job identity.
  - `operation_key` string, required: Stable logical operation identity.
  - `phase` string, required: Current producer phase.
  - `progress_current` integer, required: Completed progress units.
  - `progress_total` integer, required: Total admitted progress units.
  - `request_digest` string, required: Digest of the canonical public request.
  - `result_kind` 'places_search', required
  - `rows` PlaceSearchResultRow[], required: Preview rows; empty at admission.
    - `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.
  - `semantic_fingerprint` string, required: Digest of request and runtime semantics.
  - `source_digest` string, nullable, required: Managed source digest when supplied.
  - `status` 'queued' | 'running' | 'blocked' | 'completed' | 'failed', required: Current durable job lifecycle state.
  - `summary` PlacesSearchJobSummary, required: 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.

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