> ## Documentation Index
> Fetch the complete documentation index at: https://docs.govfiles.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get ownership search results

Read the current state of a batch owned by the authenticated account. Poll until `status` is `succeeded` or `failed`.

```bash theme={null}
curl -s 'https://api.govfiles.dev/v2/local-businesses/batches/batch_01JEXAMPLE' \
  -H "X-API-Key: $GOVFILES_API_KEY"
```

A succeeded batch includes the complete result document in `result`, including
`result.summary`, `result.credits_charged`, and one result per submitted location. The
result is returned inline; there is no separate download endpoint. Polling is not billed.

Every result includes `customer_record_id` and the submitted `restaurant`, including
unmatched results.

The API returns `404` both when the batch does not exist and when it belongs to another account.


## OpenAPI

````yaml GET /v2/local-businesses/batches/{batch_id}
openapi: 3.1.0
info:
  title: govfiles Corporate Entity API
  version: 0.2.0
  description: >-
    Search US business entity records and resolve physical local businesses to
    their legal operators and published principals.
servers:
  - url: https://api.govfiles.dev
security: []
tags:
  - name: Health
    description: Service health checks.
  - name: Companies
    description: Corporate entity search and lookup endpoints.
  - name: Officers
    description: Officer, director, and agent search endpoints.
  - name: Local Businesses
    description: >-
      Asynchronous matching of physical businesses to their legal operators and
      published principals.
  - name: Account
    description: Account and billing endpoints.
paths:
  /v2/local-businesses/batches/{batch_id}:
    get:
      tags:
        - Local Businesses
      summary: Get ownership search results
      operationId: getLocalBusinessBatch
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
            minLength: 7
            maxLength: 200
            pattern: ^batch_[0-9a-f]+$
          description: Batch identifier returned by the create endpoint.
      responses:
        '200':
          description: Current batch state.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/QueuedLocalBusinessBatch'
                    title: Queued
                  - $ref: '#/components/schemas/RunningLocalBusinessBatch'
                    title: Running
                  - $ref: '#/components/schemas/SucceededLocalBusinessBatch'
                    title: Succeeded
                  - $ref: '#/components/schemas/FailedLocalBusinessBatch'
                    title: Failed
                discriminator:
                  propertyName: status
                  mapping:
                    queued:
                      $ref: '#/components/schemas/QueuedLocalBusinessBatch'
                    running:
                      $ref: '#/components/schemas/RunningLocalBusinessBatch'
                    succeeded:
                      $ref: '#/components/schemas/SucceededLocalBusinessBatch'
                    failed:
                      $ref: '#/components/schemas/FailedLocalBusinessBatch'
        '401':
          description: Missing or invalid API key.
        '404':
          description: Batch not found or not owned by the authenticated account.
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '502':
          description: The completed result could not be loaded or validated.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    QueuedLocalBusinessBatch:
      properties:
        batch_id:
          type: string
          maxLength: 200
          minLength: 7
          pattern: ^batch_[0-9A-Za-z]+$
        type:
          type: string
          const: local_business_batch
          default: local_business_batch
        location_count:
          type: integer
          maximum: 500
          minimum: 1
        created_at:
          type: string
          format: date-time
        status:
          type: string
          const: queued
      additionalProperties: false
      type: object
      required:
        - batch_id
        - location_count
        - created_at
        - status
    RunningLocalBusinessBatch:
      properties:
        batch_id:
          type: string
          maxLength: 200
          minLength: 7
          pattern: ^batch_[0-9A-Za-z]+$
        type:
          type: string
          const: local_business_batch
          default: local_business_batch
        location_count:
          type: integer
          maximum: 500
          minimum: 1
        created_at:
          type: string
          format: date-time
        status:
          type: string
          const: running
        started_at:
          type: string
          format: date-time
      additionalProperties: false
      type: object
      required:
        - batch_id
        - location_count
        - created_at
        - status
        - started_at
    SucceededLocalBusinessBatch:
      properties:
        batch_id:
          type: string
          maxLength: 200
          minLength: 7
          pattern: ^batch_[0-9A-Za-z]+$
        type:
          type: string
          const: local_business_batch
          default: local_business_batch
        location_count:
          type: integer
          maximum: 500
          minimum: 1
        created_at:
          type: string
          format: date-time
        status:
          type: string
          const: succeeded
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        result:
          $ref: '#/components/schemas/LocalBusinessBatchResultDocument'
      additionalProperties: false
      type: object
      required:
        - batch_id
        - location_count
        - created_at
        - status
        - started_at
        - completed_at
        - result
    FailedLocalBusinessBatch:
      properties:
        batch_id:
          type: string
          maxLength: 200
          minLength: 7
          pattern: ^batch_[0-9A-Za-z]+$
        type:
          type: string
          const: local_business_batch
          default: local_business_batch
        location_count:
          type: integer
          maximum: 500
          minimum: 1
        created_at:
          type: string
          format: date-time
        status:
          type: string
          const: failed
        started_at:
          type:
            - string
            - 'null'
          format: date-time
        completed_at:
          type: string
          format: date-time
      additionalProperties: false
      type: object
      required:
        - batch_id
        - location_count
        - created_at
        - status
        - completed_at
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
      type: object
    LocalBusinessBatchResultDocument:
      properties:
        batch_id:
          type: string
          maxLength: 200
          minLength: 7
          pattern: ^batch_[0-9A-Za-z]+$
        status:
          type: string
          const: completed
        summary:
          $ref: '#/components/schemas/LocalBusinessBatchSummary'
        credits_charged:
          type: integer
          minimum: 0
        results:
          items:
            oneOf:
              - $ref: '#/components/schemas/MatchedLocalBusinessResult'
              - $ref: '#/components/schemas/UnmatchedLocalBusinessResult'
          type: array
      additionalProperties: false
      type: object
      required:
        - batch_id
        - status
        - summary
        - credits_charged
        - results
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
        msg:
          type: string
        type:
          type: string
        input: {}
        ctx:
          type: object
      type: object
      required:
        - loc
        - msg
        - type
    LocalBusinessBatchSummary:
      properties:
        submitted:
          type: integer
          minimum: 1
        matched:
          type: integer
          minimum: 0
        unmatched:
          type: integer
          minimum: 0
      additionalProperties: false
      type: object
      required:
        - submitted
        - matched
        - unmatched
    MatchedLocalBusinessResult:
      properties:
        customer_record_id:
          type: string
          maxLength: 200
          minLength: 1
        enriched_at:
          type: string
          format: date
        match:
          $ref: '#/components/schemas/MatchedMatch'
        restaurant:
          $ref: '#/components/schemas/Restaurant'
        operator:
          $ref: '#/components/schemas/Operator'
        people:
          items:
            $ref: '#/components/schemas/Person'
          type: array
      additionalProperties: false
      type: object
      required:
        - customer_record_id
        - enriched_at
        - match
        - restaurant
        - operator
    UnmatchedLocalBusinessResult:
      properties:
        customer_record_id:
          type: string
          maxLength: 200
          minLength: 1
        enriched_at:
          type: string
          format: date
        match:
          $ref: '#/components/schemas/UnmatchedMatch'
        restaurant:
          $ref: '#/components/schemas/Restaurant'
        operator:
          type: 'null'
        people:
          items:
            $ref: '#/components/schemas/Person'
          type: array
          maxItems: 0
      additionalProperties: false
      type: object
      required:
        - customer_record_id
        - enriched_at
        - match
        - restaurant
    MatchedMatch:
      properties:
        status:
          type: string
          const: matched
        relationship_status:
          $ref: '#/components/schemas/RelationshipStatus'
          default: current
      additionalProperties: false
      type: object
      required:
        - status
    Restaurant:
      properties:
        name:
          type: string
          maxLength: 500
          minLength: 1
        phone:
          type:
            - string
            - 'null'
          maxLength: 16
          minLength: 3
          pattern: ^\+[1-9][0-9]{1,14}$
          description: Phone number normalized to E.164 format.
        email:
          type:
            - string
            - 'null'
          maxLength: 320
        website:
          type:
            - string
            - 'null'
          maxLength: 2048
        address:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - name
    Operator:
      properties:
        legal_name:
          type: string
          maxLength: 500
          minLength: 1
        entity_type:
          type:
            - string
            - 'null'
          maxLength: 200
        business_registration:
          anyOf:
            - $ref: '#/components/schemas/BusinessRegistration'
            - type: 'null'
        addresses:
          items:
            $ref: '#/components/schemas/LabeledAddress'
          type: array
        last_updated_at:
          type:
            - string
            - 'null'
          format: date
        corporate_parent:
          anyOf:
            - $ref: '#/components/schemas/CorporateParent'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - legal_name
    Person:
      properties:
        name:
          type: string
          maxLength: 500
          minLength: 1
        title:
          type:
            - string
            - 'null'
          maxLength: 200
        role:
          type:
            - string
            - 'null'
          maxLength: 200
        address:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - name
      description: A human party published for the matched operator.
    UnmatchedMatch:
      properties:
        status:
          type: string
          const: unmatched
      additionalProperties: false
      type: object
      required:
        - status
    RelationshipStatus:
      type: string
      enum:
        - current
        - historical
    Address:
      properties:
        line1:
          type: string
          maxLength: 300
          minLength: 1
        line2:
          type:
            - string
            - 'null'
          maxLength: 300
        city:
          type: string
          maxLength: 150
          minLength: 1
        state:
          type: string
          pattern: ^[A-Z]{2}$
        postal_code:
          type: string
          maxLength: 20
          minLength: 1
        country:
          type: string
          pattern: ^[A-Z]{2}$
          default: US
      additionalProperties: false
      type: object
      required:
        - line1
        - city
        - state
        - postal_code
    BusinessRegistration:
      properties:
        jurisdiction:
          type: string
          maxLength: 100
          minLength: 1
        registration_number:
          type:
            - string
            - 'null'
          maxLength: 200
        status:
          type:
            - string
            - 'null'
          maxLength: 100
        incorporated_on:
          type:
            - string
            - 'null'
          format: date
        dissolved_on:
          type:
            - string
            - 'null'
          format: date
      additionalProperties: false
      type: object
      required:
        - jurisdiction
    LabeledAddress:
      properties:
        line1:
          type: string
          maxLength: 300
          minLength: 1
        line2:
          type:
            - string
            - 'null'
          maxLength: 300
        city:
          type: string
          maxLength: 150
          minLength: 1
        state:
          type: string
          pattern: ^[A-Z]{2}$
        postal_code:
          type: string
          maxLength: 20
          minLength: 1
        country:
          type: string
          pattern: ^[A-Z]{2}$
          default: US
        type:
          type: string
          maxLength: 100
          minLength: 1
      additionalProperties: false
      type: object
      required:
        - line1
        - city
        - state
        - postal_code
        - type
    CorporateParent:
      properties:
        legal_name:
          type: string
          maxLength: 500
          minLength: 1
      additionalProperties: false
      type: object
      required:
        - legal_name
      description: The legal name of a company principal associated with the operator.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````