# Bulk search progress and stats

> POST /search-files/read: follow the progress of your bulk searches and get their statistics (rows done, emails found by certainty).

Source: https://api-doc.icypeas.com/reference/bulk-files


Each bulk search creates a *file*. Read it to know how far the bulk search is and how many emails were found.

| You want | Send |
| --- | --- |
| All your bulk searches | `{}` |
| Only the ones running | `{ "status": "in_progress" }` |
| Only the finished ones | `{ "status": "done" }` |
| One bulk search | `{ "file": "kbn5421aeteb0989" }` |

A bulk search is finished when its `finished` flag is `true`. Then fetch its rows with [`/bulk-single-searchs/read`](https://api-doc.icypeas.com/reference/get-results).

> **Good to know**
>
> - Up to 50 files per call, newest first, [paginated](https://api-doc.icypeas.com/pagination).
> - Limited to **15 calls per minute**. The [bulk done webhook](https://api-doc.icypeas.com/reference/webhook-bulk-done) tells you when it's finished without polling.

**Endpoint:** `POST https://app.icypeas.com/api/search-files/read`

**Headers:** `Authorization: YOUR_API_KEY` (the key alone, no `Bearer` prefix) and `Content-Type: application/json`.

Get all your bulk searches.

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | number | no | Limit of files to fetch. Rule: default value is 10, max value is 50. |
| `file` | string | no | If you want to get a specifc bulk, please use this field with your file id |
| `status` | string | no | If you want to fetch only bulk searches that are in progress or that are done Rule: has to be either 'in_progress' or 'done'. |
| `next` | boolean | no | If you want to paginate, use this field. true = next page \| false = previous page |
| `sorts` | array | no | Array used to paginate your files, it is this item you need to pass in your requests if you want to paginate further |
| `sorts[].creationDate` | number | yes | I don't know what to write here.   |

#### Request example

```bash
curl -X POST "https://app.icypeas.com/api/search-files/read" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{
  "limit": 2
}'
```

#### Responses

##### 200: Response when your input is good.

```json
{
  "success": true,
  "files": [
    {
      "file": "#FILEID_1#",
      "system": {
        "createdAt": "2023-01-01T12:00:00.000Z",
        "modifiedAt": "2023-01-01T12:00:00.000Z"
      },
      "name": "Last File",
      "found": 250,
      "done": 300,
      "aborted": 0,
      "credits-missing": 0,
      "in-progress": 0,
      "bad-input": 0,
      "total": 300,
      "generationInProgress": true,
      "exported": false,
      "task": "email-verification",
      "finished": true
    },
    {
      "file": "#FILEID_2#",
      "system": {
        "createdAt": "2023-01-01T11:00:00.000Z",
        "modifiedAt": "2023-01-01T11:00:00.000Z"
      },
      "name": "First File",
      "found": 2500,
      "done": 2600,
      "aborted": 0,
      "bad-input": 50,
      "in-progress": 350,
      "credits-missing": 0,
      "total": 3000,
      "generationInProgress": false,
      "exported": false,
      "task": "email-search",
      "finished": false
    }
  ],
  "total": 10,
  "sorts": [
    [
      1678195083294
    ],
    [
      1678194871170
    ]
  ]
}
```

| Name | Type | Description |
| --- | --- | --- |
| `success` | boolean | This field lets you know if your request was successful |
| `files` | array | Array of your files |
| `files[].file` | string | Unique ID of your file |
| `files[].system` | object | Information concerning the search. |
| `files[].system.createdAt` | string | ISO String Date representing the creation date of the search. |
| `files[].system.modifiedAt` | string | ISO String Date representing the last modification date of the search. |
| `files[].name` | string | Name of your file |
| `files[].found` | number | Number of found items in your bulk search |
| `files[].done` | number | Number of items that are already processed |
| `files[].aborted` | number | Number of items that you have cancelled |
| `files[].credits-missing` | number | Number of items that have been cancelled by the system because you do not have enough credits |
| `files[].in-progress` | number | Number of items that are currently in progress |
| `files[].bad-input` | number | Number of items that cannot be analyzed because they are invalid (missing data, ...) |
| `files[].total` | number | Total number of items in your bulk search |
| `files[].finished` | boolean | Set to true when the bulk search has been entirely processed |
| `files[].task` | string | Task for the bulk search (email-verification, domain-search, ...) |
| `files[].generationInProgress` | boolean | Exposed for internal use only, please do not use |
| `files[].exported` | boolean | Exposed for internal use only, please do not use |
| `sorts` | array | Array used to paginate your files, it is this item you need to pass in your requests if you want to paginate further |
| `sorts[].creationDate` | number | Unix timestamp |
| `total` | number | Total number of bulk searches |

##### 200 (validation error): Response when there are validation errors.

```json
{
  "validationErrors": [
    {
      "expected": "string",
      "type": "required",
      "field": "user",
      "message": "validation_required"
    }
  ],
  "success": false
}
```

| Type | Message | Fields | When it happens |
| --- | --- | --- | --- |
| `required` | `validation_required` | `user`, `limit` | Error sent when the field is missing |
| `string` | `validation_string` | `user`, `file` | Error sent when the field is not a string |
| `stringEmpty` | `validation_string_empty` | `user` | Error sent when the field is an empty string |
| `number` | `validation_number` | `limit` | Error sent when the field 'limit' is not a number |
| `boolean` | `validation_boolean` | `next` | Error sent when the field is not a boolean |
| `array` | `validation_array` | `sorts` | Error sent when the field is not a array |
| `stringEnum` | `validation_string_enum` | `status` | When you gave a wrong status. Status should be either 'done' or 'in_progress' |

##### 401: Response when we could not authenticate you.

```json
{
  "message": "Unauthorized access.",
  "error": "UnauthorizedAccessError",
  "status": 401,
  "code": "unauthorized_access_error"
}
```

| Name | Type | Description |
| --- | --- | --- |
| `message` | string | Human-readable message. |
| `error` | string | Error name |
| `status` | number | HTTP error code |
| `code` | string | Error code |

##### 429: Error received when rate limit is exceeded

```json
{
  "message": "You have exceeded the max number of requests per minute.",
  "error": "RateLimitExceededError",
  "status": 429,
  "code": "rate_limit_exceeded_error"
}
```

| Name | Type | Description |
| --- | --- | --- |
| `message` | string | Human-readable message. |
| `error` | string | Error name |
| `status` | number | HTTP error code |
| `code` | string | Error code |