# Bulk Retrieval API

The Bulk Retrieval API provides programmatic access to enrichment data stored in Kernel.

Unlike the Inbound API which handles asynchronous enrichment workflows, the Bulk API provides direct retrieval of already-enriched data.

#### Authentication

Please contact your Kernel representative to request a token for API access.

**Token Expiration**: Tokens are valid for 7 days from the time of creation. After expiration, you will need to request a new token.

#### Pagination

The API supports pagination to handle large datasets efficiently:

* **page**: Page number (0-indexed). Default: 0
* **pageSize**: Records per page (max 1,000). Default: 1,000
* Response includes pagination metadata with total records, total pages, and navigation info

#### Response Format

The response is a JSON object containing:

* **data**: Array of enrichment records, each with an "Id" field (Salesforce ID) and dynamic fields based on your configuration
* **pagination**: Metadata including page, pageSize, totalRecords, totalPages, and hasNextPage

The exact fields returned depend on your specific configuration. Contact your Kernel representative for details on your field mappings.

#### Rate Limits

The API enforces rate limiting to ensure fair usage:

* **Rate Limit**: 5 requests per second per token
* **429 Response**: When rate limit is exceeded, you'll receive a 429 status code. Please wait before retrying.

#### Error Handling

* **401 Unauthorized**: Invalid or expired token
* **400 Bad Request**: Missing or invalid query parameters
* **500 Internal Server Error**: Server-side error occurred<br>

## Retrieve enrichment data

> Retrieve enrichment data for your organization using token-based authentication.\
> \
> The response is paginated and contains only the fields configured in your bulk API setup. The structure is dynamic and depends on your specific field mappings.\
> \
> Use the \`page\` and \`pageSize\` query parameters to navigate through large datasets. The response includes pagination metadata to help you iterate through all pages.

```json
{"openapi":"3.1.0","info":{"title":"Kernel Bulk Retrieval API","version":"1.0.0"},"paths":{"/api/v1/bulk/retrieval":{"get":{"tags":["Bulk Retrieval"],"summary":"Retrieve enrichment data","description":"Retrieve enrichment data for your organization using token-based authentication.\n\nThe response is paginated and contains only the fields configured in your bulk API setup. The structure is dynamic and depends on your specific field mappings.\n\nUse the `page` and `pageSize` query parameters to navigate through large datasets. The response includes pagination metadata to help you iterate through all pages.","parameters":[{"in":"query","name":"token","schema":{"type":"string","description":"Authentication token for bulk API access"},"required":true,"description":"Authentication token for bulk API access"},{"in":"query","name":"page","schema":{"default":0,"description":"Page number for pagination (0-indexed)","type":"integer","minimum":0,"maximum":9007199254740991},"description":"Page number for pagination (0-indexed)"},{"in":"query","name":"pageSize","schema":{"default":1000,"description":"Number of records per page (max 1000)","type":"integer","exclusiveMinimum":0,"maximum":1000},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"Enrichment data retrieved successfully. Returns a paginated response with data array and pagination metadata.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"Id":{"type":"string","description":"Salesforce ID of the record"}},"required":["Id"],"additionalProperties":{},"description":"Enrichment data record. Always includes an \"Id\" field (Salesforce ID), plus dynamic fields based on your configuration."},"description":"Array of enrichment data records. Each record includes an \"Id\" field (Salesforce ID) and dynamic fields based on client configuration."},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Current page number (0-indexed)"},"pageSize":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Number of records per page"},"totalRecords":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Total number of records matching the filter"},"totalPages":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Total number of pages available"},"hasNextPage":{"type":"boolean","description":"Whether there are more pages available"}},"required":["page","pageSize","totalRecords","totalPages","hasNextPage"],"additionalProperties":false,"description":"Pagination metadata for the response"}},"required":["data","pagination"],"additionalProperties":false,"description":"Paginated response containing enrichment data and pagination metadata"}}}},"400":{"description":"400 Bad Request - Missing or invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining what went wrong"}},"required":["error"],"additionalProperties":false,"description":"Error response from bulk retrieval endpoint"}}}},"401":{"description":"401 Unauthorized - Invalid or expired token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining what went wrong"}},"required":["error"],"additionalProperties":false,"description":"Error response from bulk retrieval endpoint"}}}},"500":{"description":"500 Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining what went wrong"}},"required":["error"],"additionalProperties":false,"description":"Error response from bulk retrieval endpoint"}}}}}}}}}
```