> ## Documentation Index > Fetch the complete documentation index at: https://docs.baselayer.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Search Batch > Retrieve a SearchBatch by ID and return it in `SearchBatchResponse` format. The two TIN counts are computed per request rather than stored. ``tin_matching_pending_count`` counts the batch's searches still inside the IRS TIN-match retry budget, so it falls as verdicts land; while it is positive the batch's exports are a provisional snapshot that will be regenerated — ``exports_generated_at`` moves forward each time — so a caller that cached a download should re-read this response before trusting it. It reaching zero means nothing is left to retry, NOT that every TIN was verified. ``tin_matching_unresolved_count`` is the companion that says how many rows FINISHED without a verdict and dropped out of the retry pool (budget spent, retries disabled for the program, or the search cancelled). Both come from one scan so they cannot disagree. The two do not partition the batch's TIN rows: a search that is still running is in neither, because its TIN match has not been attempted to a conclusion. On a ``COMPLETED`` batch two zeroes therefore do mean every TIN was verified; on one still processing they mean only that nothing has been given up on yet. ## OpenAPI ````yaml /api-reference/openapi.json get /searches/batch/{id} openapi: 3.1.0 info: title: baselayer-api-service version: 0.1.0 servers: - url: https://api.baselayer.com/ security: [] paths: /searches/batch/{id}: get: tags: - Search summary: Get Search Batch description: >- Retrieve a SearchBatch by ID and return it in `SearchBatchResponse` format. The two TIN counts are computed per request rather than stored. ``tin_matching_pending_count`` counts the batch's searches still inside the IRS TIN-match retry budget, so it falls as verdicts land; while it is positive the batch's exports are a provisional snapshot that will be regenerated — ``exports_generated_at`` moves forward each time — so a caller that cached a download should re-read this response before trusting it. It reaching zero means nothing is left to retry, NOT that every TIN was verified. ``tin_matching_unresolved_count`` is the companion that says how many rows FINISHED without a verdict and dropped out of the retry pool (budget spent, retries disabled for the program, or the search cancelled). Both come from one scan so they cannot disagree. The two do not partition the batch's TIN rows: a search that is still running is in neither, because its TIN match has not been attempted to a conclusion. On a ``COMPLETED`` batch two zeroes therefore do mean every TIN was verified; on one still processing they mean only that nothing has been given up on yet. operationId: get_search_batch_searches_batch__id__get parameters: - name: id in: path required: true schema: type: string format: uuid title: Batch ID description: >- The unique identifier of the search batch to retrieve searches for. examples: - a3c16db9-52f0-4f67-9ce3-0fae6f9f3f31 - 3b7b12c4-12e4-4f2e-9b67-1a9e34339372 description: The unique identifier of the search batch to retrieve searches for. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/v1.BusinessSearchBatchResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: v1.BusinessSearchBatchResponse: properties: id: type: string format: uuid title: Id description: Unique identifier for the business search batch. name: type: string title: Name description: The name of the business search batch. state: $ref: '#/components/schemas/TaskState' description: The current state of the business search batch. progress: anyOf: - type: number maximum: 1 minimum: 0 - type: 'null' title: Progress description: Processing progress from 0.0 to 1.0. Null if not yet started. examples: - 0 - 0.45 - 1 completed_count: anyOf: - type: integer minimum: 0 - type: 'null' title: Completed Count description: Number of rows that have been processed. Null if not yet started. total_count: anyOf: - type: integer minimum: 0 - type: 'null' title: Total Count description: Total number of rows to process. Null if not yet started. created_at: type: string format: date-time title: Created At description: The datetime the business search batch was created. options: items: type: string enum: - Order.WebsiteAnalysis - Order.NaicsPrediction - Order.Pep - Order.Enhanced title: BusinessSearchOptions type: array title: Options description: Optional features to enable during business search execution. default: [] examples: - - Order.WebsiteAnalysis warnings: items: type: string type: array title: Warnings description: Any warnings that occurred. default: [] export_csv_uri: anyOf: - type: string - type: 'null' title: Export Csv Uri description: >- GCS URI for the pre-computed CSV export. Available after batch completion. export_jsonl_uri: anyOf: - type: string - type: 'null' title: Export Jsonl Uri description: >- GCS URI for the pre-computed JSONL export. Available after batch completion. report_version: anyOf: - type: integer - type: 'null' title: Report Version description: Report schema version. Available after batch completion. exports_generated_at: anyOf: - format: date-time type: string - type: 'null' title: Exports Generated At description: >- When the export artifacts above were generated. Null until the batch first exports. This moves forward whenever the exports are regenerated because late TIN verdicts changed the results, so compare it against the value you last downloaded to tell whether your copy is current. tin_matching_pending_count: type: integer minimum: 0 title: Tin Matching Pending Count description: >- How many of this batch's searches have concluded still awaiting a TIN verification verdict from the IRS AND will be retried to get one. A positive count means the exports are provisional: those rows report a pending TIN status today, and the files and report will be regenerated once the verdicts land. Zero means nothing is left to retry, so the exports will not change again on their own — it does NOT mean every TIN was verified. Rows whose retries ran out, or whose program has TIN-match retries switched off, leave this count without an answer; `tin_matching_unresolved_count` reports those. A search that is still running is in neither count, because its TIN match has not been attempted to a conclusion yet — so on a batch that has not reached `COMPLETED`, both counts can read zero with verifications still to come. default: 0 examples: - 0 - 12 tin_matching_unresolved_count: type: integer minimum: 0 title: Tin Matching Unresolved Count description: >- How many of this batch's searches supplied a TIN, finished without a verification verdict, and will not be retried for one — the retry attempts were used up, the program has TIN-match retries switched off, the search was cancelled, or it was made against a sandbox application. These rows are final at a non-matched status: waiting longer will not change them, and re-submitting the search is the only way to try again. Counted alongside `tin_matching_pending_count` rather than folded into it, because a batch can settle (pending zero) with unresolved rows still in it. A search that has not finished is in neither count — nothing has been given up on yet — so both reading zero on a batch that is still running does not mean every TIN was verified. default: 0 examples: - 0 - 3 questionnaire: anyOf: - $ref: '#/components/schemas/DataTestQuestionnaire' - type: 'null' description: Data-test questionnaire answers submitted with the batch, if any. type: object required: - id - name - state - created_at title: BusinessSearchBatchResponse (v1) description: >- Represents a batch business search response. For real-time progress updates during batch processing, subscribe to SSE events on the /events endpoint and listen for SearchBatch.progress events. A batch's export artifacts are a point-in-time snapshot, stamped with ``exports_generated_at``. Some TIN (EIN) verifications are still resolving against the IRS when that snapshot is taken, so a batch can finish with verdicts still outstanding — ``tin_matching_pending_count`` says how many. While that count is positive the exports are provisional: as each verdict lands the batch's files and report are regenerated in place, and ``exports_generated_at`` moves forward. Subscribe to ``SearchBatch.exports_refreshed`` on the /events endpoint, or the ``SearchBatch.updated`` webhook, to be told when a regeneration lands rather than polling for it. Once ``tin_matching_pending_count`` reaches zero the exports have settled — but that is a statement about the retrying, not about the verdicts. A search can run out of retry attempts, or belong to a program that has TIN-match retries switched off, and it then leaves the pending count without ever getting an answer. ``tin_matching_unresolved_count`` is how many such rows the batch ended up with: they report a non-final TIN status in the exports and will not change again. Neither count includes a search that is still running, because such a row has not attempted its TIN match to a conclusion yet. Both counts at zero therefore means only "nothing is awaiting a retry and nothing has been given up on" — read together with ``state``, it means every TIN was verified on a ``COMPLETED`` batch, and nothing more than "no verdict has been missed yet" on one that is still ``PENDING`` or ``EXECUTING``. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError TaskState: enum: - PENDING - EXECUTING - COMPLETED - FAILED - CANCELLED title: TaskState type: string DataTestQuestionnaire: properties: kyb: anyOf: - $ref: '#/components/schemas/DataTestKYBAnswers' - type: 'null' web_presence: anyOf: - $ref: '#/components/schemas/DataTestWebPresenceAnswers' - type: 'null' liens: anyOf: - $ref: '#/components/schemas/DataTestLiensAnswers' - type: 'null' litigations: anyOf: - $ref: '#/components/schemas/DataTestLitigationsAnswers' - type: 'null' type: object title: DataTestQuestionnaire description: |- Answers collected from the data-test Product Selection step. Persisted on the parent :class:`osiris.models.SearchBatch` row as a JSONB column for later analysis, and echoed to Slack for real-time ops visibility. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError DataTestKYBAnswers: properties: current_provider: anyOf: - type: string - type: 'null' title: Current Provider examples: - Middesk new_applications_per_month: anyOf: - type: integer minimum: 0 - type: 'null' title: New Applications Per Month examples: - 500 avg_uw_time_hours: anyOf: - type: integer minimum: 0 - type: 'null' title: Avg Uw Time Hours examples: - 24 avg_uw_time_minutes: anyOf: - type: integer maximum: 59 minimum: 0 - type: 'null' title: Avg Uw Time Minutes examples: - 2 match_rate_pct: anyOf: - type: number maximum: 100 minimum: 0 - type: 'null' title: Match Rate Pct examples: - 25 approval_rate_pct: anyOf: - type: number maximum: 100 minimum: 0 - type: 'null' title: Approval Rate Pct examples: - 72 type: object title: DataTestKYBAnswers description: Business Verification / KYB answers from the data-test questionnaire. DataTestWebPresenceAnswers: properties: existing_workflow_step: anyOf: - type: boolean - type: 'null' title: Existing Workflow Step current_provider: anyOf: - type: string - type: 'null' title: Current Provider examples: - Built in-house type: object title: DataTestWebPresenceAnswers description: |- Web Presence Review answers from the data-test questionnaire. The list of sub-products the prospect opted into for Web Presence (Industry Prediction, Website Analysis, etc.) is deliberately not captured here — those selections are already represented by :class:`osiris.enums.BusinessSearchOptions` on the parent batch (``options`` on :class:`BusinessSearchBatchRequest`). DataTestLiensAnswers: properties: current_provider: anyOf: - type: string - type: 'null' title: Current Provider examples: - LexisNexis type: object title: DataTestLiensAnswers description: Liens Search answers from the data-test questionnaire. DataTestLitigationsAnswers: properties: current_provider: anyOf: - type: string - type: 'null' title: Current Provider examples: - LexisNexis type: object title: DataTestLitigationsAnswers description: Litigations Search answers from the data-test questionnaire. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````