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

# Query Batch Enrichment Status

> Query the status of multiple enrichment tasks in a single batch request

This endpoint allows you to efficiently check the status of multiple enrichment operations at once. Instead of making individual requests for each entity, you can query up to 200 enrichment tasks in a single batch request. This is particularly useful when polling for enrichment completion across multiple leads.

## Authentication

This endpoint requires authentication with a valid organization context.

<Note>
  Requests without a valid organization ID will receive a `400 Bad Request`
  response with the message "Organization ID is missing".
</Note>

## Request

<ParamField body="tasks" type="array" required>
  An array of enrichment task queries. Each task specifies an entity and the
  enrichment field to check. **Constraints:** - Minimum: 1 task - Maximum: 200
  tasks per batch

  <Expandable title="Task Object Properties">
    <ParamField body="entityId" type="string" required>
      The UUID of the entity (person or company) to query enrichment status for.
      **Format:** UUID v4 **Example:** `"550e8400-e29b-41d4-a716-446655440000"`
    </ParamField>

    <ParamField body="field" type="string" required>
      The enrichment field to query. **Allowed values:** - `phones` - Phone
      number enrichment - `emails` - Email address enrichment - `summary` -
      AI-generated summary enrichment
    </ParamField>

    <ParamField body="entityType" type="string" default="person">
      The type of entity being queried. **Allowed values:** - `person` -
      Individual contact (default) - `company` - Company/organization
    </ParamField>
  </Expandable>
</ParamField>

## Response

The response is an array of enrichment objects for tasks that have enrichment records. Tasks without existing enrichment records are omitted from the response.

<ResponseField name="enrichments" type="array">
  Array of enrichment status objects. May be shorter than the input if some
  entities don't have enrichment records.

  <Expandable title="Enrichment Object Properties">
    <ResponseField name="id" type="string" required>
      Unique identifier for the enrichment record. **Format:** UUID v4
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      Timestamp when the enrichment was created. **Format:** ISO 8601 datetime
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      Timestamp when the enrichment was last updated. **Format:** ISO 8601
      datetime
    </ResponseField>

    <ResponseField name="entityId" type="string" required>
      The UUID of the entity this enrichment belongs to.
    </ResponseField>

    <ResponseField name="entityType" type="string" required>
      The type of entity: `person`, `company`, or `leadlist`.
    </ResponseField>

    <ResponseField name="field" type="string" required>
      The enrichment field: `phones`, `emails`, or `summary`.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Current status of the enrichment. **Possible values:** - `pending` -
      Enrichment is in progress - `finished` - Enrichment completed successfully

      * `failed` - Enrichment failed due to an error - `timeout` - Enrichment
        exceeded maximum processing time - `cancelled` - Enrichment was cancelled
    </ResponseField>

    <ResponseField name="error" type="string | null">
      Error message if the enrichment failed. `null` for successful or pending
      enrichments.
    </ResponseField>

    <ResponseField name="dataFound" type="boolean | null">
      Whether data was found during enrichment. - `null` - Unknown or enrichment
      still pending - `true` - Data was found and enriched - `false` - No data
      found for this entity
    </ResponseField>

    <ResponseField name="createdBy" type="string" required>
      User ID who initiated the enrichment.
    </ResponseField>

    <ResponseField name="orgId" type="string" required>
      Organization ID the enrichment belongs to.
    </ResponseField>

    <ResponseField name="globalEnrichmentId" type="string | null">
      Reference to the global enrichment record if data was cached globally.
    </ResponseField>

    <ResponseField name="creditTransactionId" type="string | null">
      Reference to the credit transaction if credits were consumed.
    </ResponseField>

    <ResponseField name="value" type="unknown | null">
      Optional enrichment payload value. Present for enrichments that return data (e.g., company summaries). `null` or omitted for standard phone/email enrichments.
    </ResponseField>
  </Expandable>
</ResponseField>

## Use Cases

### Polling for Enrichment Completion

When you trigger batch enrichment for multiple leads, use this endpoint to poll for completion status:

1. Trigger batch enrichment via the enrichment trigger endpoint
2. Store the entity IDs and fields being enriched
3. Periodically call this endpoint to check status
4. Process leads as their enrichments complete

### Checking Pre-existing Enrichments

Before triggering new enrichments, use this endpoint to check which entities already have enrichment data, avoiding duplicate processing and unnecessary credit consumption.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.lance.app/api/v1/operations/enrichment/batch/query" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <token>" \
    -d '{
      "tasks": [
        {
          "entityId": "550e8400-e29b-41d4-a716-446655440000",
          "field": "phones"
        },
        {
          "entityId": "550e8400-e29b-41d4-a716-446655440001",
          "field": "emails"
        },
        {
          "entityId": "660e8400-e29b-41d4-a716-446655440002",
          "field": "summary",
          "entityType": "company"
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("/api/v1/operations/enrichment/batch/query", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer <token>",
    },
    body: JSON.stringify({
      tasks: [
        {
          entityId: "550e8400-e29b-41d4-a716-446655440000",
          field: "phones",
        },
        {
          entityId: "550e8400-e29b-41d4-a716-446655440001",
          field: "emails",
        },
        {
          entityId: "660e8400-e29b-41d4-a716-446655440002",
          field: "summary",
          entityType: "company",
        },
      ],
    }),
  });

  const enrichments = await response.json();
  ```

  ```typescript TypeScript theme={null}
  interface EnrichmentTask {
    entityId: string;
    field: "phones" | "emails" | "summary";
    entityType?: "person" | "company";
  }

  interface Enrichment {
    id: string;
    createdAt: string;
    updatedAt: string;
    entityId: string;
    entityType: "person" | "company" | "leadlist";
    field: string;
    status: "pending" | "finished" | "failed" | "timeout" | "cancelled";
    error: string | null;
    dataFound: boolean | null;
    createdBy: string;
    orgId: string;
    globalEnrichmentId: string | null;
    creditTransactionId: string | null;
  }

  const tasks: EnrichmentTask[] = [
    { entityId: "550e8400-e29b-41d4-a716-446655440000", field: "phones" },
    { entityId: "550e8400-e29b-41d4-a716-446655440001", field: "emails" },
    {
      entityId: "660e8400-e29b-41d4-a716-446655440002",
      field: "summary",
      entityType: "company",
    },
  ];

  const response = await fetch("/api/v1/operations/enrichment/batch/query", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({ tasks }),
  });

  const enrichments: Enrichment[] = await response.json();

  // Check for completed enrichments
  const completed = enrichments.filter((e) => e.status === "finished");
  const pending = enrichments.filter((e) => e.status === "pending");
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "createdAt": "2025-01-13T10:30:00.000Z",
      "updatedAt": "2025-01-13T10:30:15.000Z",
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "entityType": "person",
      "field": "phones",
      "status": "finished",
      "error": null,
      "dataFound": true,
      "createdBy": "user_abc123",
      "orgId": "org_xyz789",
      "globalEnrichmentId": "global_123",
      "creditTransactionId": "credit_456"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "createdAt": "2025-01-13T10:30:00.000Z",
      "updatedAt": "2025-01-13T10:30:00.000Z",
      "entityId": "550e8400-e29b-41d4-a716-446655440001",
      "entityType": "person",
      "field": "emails",
      "status": "pending",
      "error": null,
      "dataFound": null,
      "createdBy": "user_abc123",
      "orgId": "org_xyz789",
      "globalEnrichmentId": null,
      "creditTransactionId": null
    }
  ]
  ```

  ```json Success Response (Empty - No Enrichments Found) theme={null}
  []
  ```

  ```json Error Response (Validation Error - Empty Tasks) theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "At least one task is required"
    }
  }
  ```

  ```json Error Response (Validation Error - Too Many Tasks) theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Maximum 200 tasks allowed per batch"
    }
  }
  ```

  ```json Error Response (Validation Error - Invalid Entity ID) theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid uuid"
    }
  }
  ```

  ```json Error Response (Validation Error - Invalid Field) theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid enum value. Expected 'phones' | 'emails' | 'summary', received 'invalid'"
    }
  }
  ```

  ```json Error Response (Authentication Error) theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Organization ID is missing"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Status Code | Error Code         | Description                                                        |
| ----------- | ------------------ | ------------------------------------------------------------------ |
| `400`       | `VALIDATION_ERROR` | Invalid request body, empty tasks array, or exceeds 200 task limit |
| `401`       | `UNAUTHORIZED`     | Missing or invalid authentication                                  |
| `500`       | `INTERNAL_ERROR`   | Server error during enrichment query                               |

## Notes

* The response array may be shorter than the input tasks array if some entities don't have enrichment records
* Enrichments that exceed the maximum processing time are automatically marked as `timeout` status
* The `dataFound` field is `null` while enrichment is pending and becomes `true` or `false` upon completion
* This endpoint is read-only and does not trigger new enrichments or consume credits
* For efficient polling, consider implementing exponential backoff when checking for pending enrichments