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

# Stop a contact search

> Cancel a running search's outstanding provider jobs. What it had already found stays in the list, and the search moves to phase `Cancelled` rather than `Done` — it did not run to completion, and was not meant to.

Stopping an already-finished search is not an error: it cancels nothing and reports `stopped_count: 0`.



## OpenAPI

````yaml /reference/openapi.yaml post /v2/contact-searches/{searchID}/stop
openapi: 3.1.0
info:
  title: Tamtam Public API
  version: 2.0.0
servers:
  - url: https://api.tamtam.ai/api
security: []
paths:
  /v2/contact-searches/{searchID}/stop:
    post:
      tags:
        - Contact Searches
      summary: Stop a contact search
      description: >-
        Cancel a running search's outstanding provider jobs. What it had already
        found stays in the list, and the search moves to phase `Cancelled`
        rather than `Done` — it did not run to completion, and was not meant to.


        Stopping an already-finished search is not an error: it cancels nothing
        and reports `stopped_count: 0`.
      operationId: stop-contact-search
      parameters:
        - description: Contact search UUID
          in: path
          name: searchID
          required: true
          schema:
            description: Contact search UUID
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StopContactSearchOutputBody'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
        - apikeyAuth: []
        - bearerAuth: []
components:
  schemas:
    StopContactSearchOutputBody:
      additionalProperties: false
      properties:
        contact_search_id:
          type: string
        status:
          $ref: '#/components/schemas/ContactSearchStatusDto'
          description: The search's status after the stop.
        stopped_count:
          description: >-
            How many of the search's outstanding provider jobs this call
            cancelled. Zero when the search had already finished, which is not
            an error.
          format: int64
          type: integer
      required:
        - contact_search_id
        - stopped_count
        - status
      type: object
    ErrorModel:
      additionalProperties: false
      properties:
        detail:
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
            - array
            - 'null'
        instance:
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: >-
            A short, human-readable summary of the problem type. This value
            should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
      type: object
    ContactSearchStatusDto:
      additionalProperties: false
      properties:
        cancelled_jobs:
          description: >-
            Child jobs cancelled by a stop. Non-zero is what makes the phase
            Cancelled.
          format: int64
          type: integer
        companies_searched:
          description: Companies the search actually reached.
          format: int64
          type: integer
        contacts_in_list_count:
          description: >-
            Deduplicated contacts actually in the list. The number to report
            once the search is done.
          format: int64
          type: integer
        done_jobs:
          description: >-
            Child jobs in a terminal state. Poll total_jobs/done_jobs for
            progress.
          format: int64
          type: integer
        empty_reason:
          description: >-
            Why a finished search produced no contacts. Absent while it is
            running and whenever contacts were found.
          type: string
        phase:
          description: >-
            Searching while any child job is outstanding; Done once every one
            has finished; Cancelled when the search was stopped. There is no
            Failed: a search whose provider calls all failed reports Done with
            empty_reason saying so.
          enum:
            - Searching
            - Done
            - Cancelled
          type: string
        skipped_deleted_company_jobs:
          description: >-
            Child searches refused before dispatch because the company's
            LinkedIn page is gone. Never charged.
          format: int64
          type: integer
        total_jobs:
          description: Child jobs across every (query, company) pair.
          format: int64
          type: integer
        total_processed_results:
          description: >-
            Profiles processed so far, double-counting anyone found by more than
            one query. A live progress indicator, not a result count.
          format: int64
          type: integer
      required:
        - phase
        - total_jobs
        - done_jobs
        - total_processed_results
        - contacts_in_list_count
        - companies_searched
        - skipped_deleted_company_jobs
        - cancelled_jobs
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
  securitySchemes:
    apikeyAuth:
      description: Account API key passed in the Authorization header
      in: header
      name: Authorization
      type: apiKey
    bearerAuth:
      description: Bearer JWT obtained via the OAuth 2.1 authorization flow
      scheme: bearer
      type: http

````