Bulk search progress

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.

Good to know

• Up to 50 files per call, newest first, paginated.
• Limited to 15 calls per minute. The bulk done webhook tells you when it's finished without polling.

POSThttps://app.icypeas.com/api/search-files/read

Get all your bulk searches.

Headers

• Authorizationstringrequired

  Your API key, as is (no Bearer prefix).

• Content-Typestringrequired

  Always application/json.

Body parameters

• limitnumberoptional

  Limit of files to fetch.

  Rule: default value is 10, max value is 50

• filestringoptional

  If you want to get a specifc bulk, please use this field with your file id

• statusstringoptional

  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'

• nextbooleanoptional

  If you want to paginate, use this field. true = next page | false = previous page

• sortsarray of objectsoptional

  Array used to paginate your files, it is this item you need to pass in your requests if you want to paginate further

  Show item properties (1)

  • creationDatenumberrequired

    I don't know what to write here.

Request example

cURL

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

JavaScript

const response = await fetch("https://app.icypeas.com/api/search-files/read", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "YOUR_API_KEY",
  },
  body: JSON.stringify({
    "limit": 2
  }),
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://app.icypeas.com/api/search-files/read",
    headers={"Authorization": "YOUR_API_KEY"},
    json={
        "limit": 2,
    },
)
print(response.json())

PHP

<?php
$body = <<<'JSON'
{
    "limit": 2
}
JSON;

$ch = curl_init("https://app.icypeas.com/api/search-files/read");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: YOUR_API_KEY",
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

PowerShell

$headers = @{
  "Authorization" = "YOUR_API_KEY"
  "Content-Type"  = "application/json"
}

$body = @'
{
  "limit": 2
}
'@

$response = Invoke-RestMethod -Method POST -Uri "https://app.icypeas.com/api/search-files/read" -Headers $headers -Body $body
$response | ConvertTo-Json -Depth 10

JSON body

Paste this in the Body field of Make, Zapier, n8n or Postman.

{
  "limit": 2
}

Responses

200SuccessResponse when your input is good.

Example response · 200

{
  "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
    ]
  ]
}

Response fields

• successboolean

  This field lets you know if your request was successful

• filesarray of objects

  Array of your files

  Show item properties (14)

  • filestring

    Unique ID of your file

  • systemobject

    Information concerning the search.

    Show properties (2)

    • createdAtstring

      ISO String Date representing the creation date of the search.

    • modifiedAtstring

      ISO String Date representing the last modification date of the search.

  • namestring

    Name of your file

  • foundnumber

    Number of found items in your bulk search

  • donenumber

    Number of items that are already processed

  • abortednumber

    Number of items that you have cancelled

  • credits-missingnumber

    Number of items that have been cancelled by the system because you do not have enough credits

  • in-progressnumber

    Number of items that are currently in progress

  • bad-inputnumber

    Number of items that cannot be analyzed because they are invalid (missing data, ...)

  • totalnumber

    Total number of items in your bulk search

  • finishedboolean

    Set to true when the bulk search has been entirely processed

  • taskstring

    Task for the bulk search (email-verification, domain-search, ...)

  • generationInProgressboolean

    Exposed for internal use only, please do not use

  • exportedboolean

    Exposed for internal use only, please do not use

• sortsarray of objects

  Array used to paginate your files, it is this item you need to pass in your requests if you want to paginate further

  Show item properties (1)

  • creationDatenumber

    Unix timestamp

• totalnumber

  Total number of bulk searches

200Validation errorResponse when there are validation errors.

The request reached Icypeas but some fields are wrong. The response lists every problem in validationErrors. See how to read and fix errors.

Example response · 200

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

Type	Fields	When it happens
required validation_required	userlimit	Error sent when the field is missing
string validation_string	userfile	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'

401UnauthorizedResponse when we could not authenticate you.

Example response · 401

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

Response fields

• messagestring

  Human-readable message.

• errorstring

  Error name

• statusnumber

  HTTP error code

• codestring

  Error code

429Too many requestsError received when rate limit is exceeded

Example response · 429

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

Response fields

• messagestring

  Human-readable message.

• errorstring

  Error name

• statusnumber

  HTTP error code

• codestring

  Error code