### RangeWithTypeRetailSize Example

Source: https://docs.ai-ark.com/reference/company-search-1

An example of the RangeWithTypeRetailSize schema, showing a single retail size range.

```json
{
          "type": "RANGE",
          "range": [
            {
              "start": 1,
              "end": 10
            }
          ]
        }
```

--------------------------------

### RangeWithTypeEmployeeSize Example

Source: https://docs.ai-ark.com/reference/company-search-1

An example of the RangeWithTypeEmployeeSize schema, demonstrating how to specify multiple employee size ranges.

```json
{
          "type": "RANGE",
          "range": [
            {
              "start": 1,
              "end": 10
            },
            {
              "start": 100,
              "end": 500
            }
          ]
        }
```

--------------------------------

### Response Example for Save List

Source: https://docs.ai-ark.com/reference/save-list

This is an example of a successful response when a list is created or updated. It includes the list's ID, workspace, type, values, and creation timestamp.

```json
{
  "id": "294ce93e-8881-414c-8951-e91b5df7f560",
  "workspace": "your-workspace-id",
  "type": "people_id",
  "values": [
    "d39d88bf-6ec5-8915-77db-3145472cf706",
    "8c83763c-efed-89ba-e651-8e66b286005e"
  ],
  "created": 1778064460905
}
```

--------------------------------

### Credits Response Example

Source: https://docs.ai-ark.com/reference/fetch-credit

This is an example of a successful response when fetching your credits. The 'total' field indicates the number of credits remaining in your account.

```json
{
  "total": 100
}
```

--------------------------------

### Example: Filter by Previous Job Title

Source: https://docs.ai-ark.com/reference/people-search-1

This example demonstrates filtering by previous job titles, specifying 'any' and 'all' conditions for inclusion and exclusion. The 'mode' is set to 'SMART'.

```json
{
  "any": {
    "include": {
      "mode": "SMART",
      "content": [
        "founder"
      ]
    },
    "exclude": {
      "mode": "SMART",
      "content": [
        "head"
      ]
    }
  },
  "all": {
    "include": {
      "mode": "SMART",
      "content": [
        "intern"
      ]
    },
    "exclude": {
      "mode": "SMART",
      "content": [
        "senior"
      ]
    }
  }
}
```

--------------------------------

### Error Response Example

Source: https://docs.ai-ark.com/reference/save-list

Example of a bad request response, indicating missing type, excessive values, or quota exceeded.

```APIDOC
## Error Response

### Description
Bad Request — missing `type` on insert, `values` exceeds 10,000, or daily-quota exceeded.

### Response Example (400)
```json
{
  "timestamp": "2026-05-06T10:00:00.000Z",
  "status": 400,
  "error": "terms_lookup_list_values_limit_exceeded 10000",
  "path": ""
}
```
```

--------------------------------

### OpenAPI Schema Example

Source: https://docs.ai-ark.com/reference/save-list

This example demonstrates a typical error response schema for a bad request, including details like timestamp, status, error message, and path.

```json
{
  "timestamp": "2026-05-06T10:00:00.000Z",
  "status": 400,
  "error": "terms_lookup_list_values_limit_exceeded 10000",
  "path": ""
}
```

--------------------------------

### Example: Filter by Current Job Title

Source: https://docs.ai-ark.com/reference/people-search-1

This example shows how to filter by the current job title, using 'all' and 'any' conditions for inclusion and exclusion. The 'mode' is set to 'SMART'.

```json
{
  "all": {
    "include": {
      "mode": "SMART",
      "content": [
        "founder"
      ]
    },
    "exclude": {
      "mode": "SMART",
      "content": [
        "senior"
      ]
    }
  },
  "any": {
    "include": {
      "mode": "SMART",
      "content": [
        "intern"
      ]
    },
    "exclude": {
      "mode": "SMART",
      "content": [
        "head"
      ]
    }
  }
}
```

--------------------------------

### Example: Filter by Latest Active Position

Source: https://docs.ai-ark.com/reference/people-search-1

This example demonstrates how to filter search results to include only the latest active position. It corresponds to the 'Latest Active Position Only' toggle in the UI.

```json
{
  "latest": {
    "duration": {
      "latestCompany": {
        "min": {
          "year": 1,
          "month": 0
        },
        "max": {
          "year": 4,
          "month": 0
        }
      },
      "latestJob": {
        "min": {
          "year": 0,
          "month": 6
        },
        "max": {
          "year": 2,
          "month": 6
        }
      }
    }
  }
}
```

--------------------------------

### Get Email Finder Results by Track ID

Source: https://docs.ai-ark.com/reference/get-email-finder-results-by-track-id

Make a GET request to retrieve paginated email finder results for a given track ID. Use 'page' and 'size' query parameters for pagination. The track ID is obtained from a previous 'Find Emails by Track ID' response.

```shell
curl --request GET \
     --url 'https://api.ai-ark.com/api/developer-portal/v1/people/email-finder/719aba5a-876f-4690-bb57-5157153836b4/inquiries?page=0&size=10' \
     --header 'accept: application/json'
```

--------------------------------

### Email Finder Results Response

Source: https://docs.ai-ark.com/reference/get-email-finder-results-by-track-id

Example of a successful response body containing paginated email finder inquiries. Each inquiry includes input details and a list of output email addresses with their verification status.

```json
{
  "content": [
    {
      "refId": "ee0bf902-00c7-deff-1fda-45bedef39602",
      "state": "DONE",
      "input": {
        "firstname": "Christopher",
        "lastname": "Sparks",
        "domain": "themetalmaniacs.com"
      },
      "output": [
        {
          "address": "csparks@themetalmaniacs.com",
          "mx": {
            "record": "mx1.example.com",
            "google": false,
            "found": true,
            "provider": "google"
          },
          "domainType": "SMTP",
          "status": "VALID",
          "subStatus": "EMPTY",
          "date": "2026-03-13T09:28:35.000779",
          "free": false,
          "generic": false,
          "found": true
        }
      ]
    }
  ],
  "size": 10,
  "totalElements": 100,
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10,
    "sort": {
      "empty": true,
      "sorted": false,
      "unsorted": true
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  }
}
```

--------------------------------

### Successful Export Response

Source: https://docs.ai-ark.com/reference/people-export-with-email

This is an example of a successful response when initiating an export job. It includes a 'trackId' for monitoring the job, 'statistics' on the export process, and the initial 'state' of the job, which is typically 'PENDING'.

```json
{
  "trackId": "87dad120-e371-44e0-b896-cf90b2f84170",
  "statistics": {
    "total": 25,
    "found": 0
  },
  "webhook": {
    "state": "PENDING",
    "retry": null
  },
  "state": "PENDING",
  "description": null
}
```

--------------------------------

### Fetch Credits cURL Request

Source: https://docs.ai-ark.com/reference/fetch-credit

Use this cURL command to make a GET request to the AI Ark API to retrieve your remaining credits. Ensure the 'accept' header is set to 'application/json'.

```shell
curl --request GET \
     --url https://api.ai-ark.com/api/developer-portal/v1/payments/credits \
     --header 'accept: application/json'
```

--------------------------------

### Get Email Finder Statistics (cURL)

Source: https://docs.ai-ark.com/reference/get-email-finder-statistics-by-track-id

Use this cURL command to make a GET request to the Email Finder Statistics endpoint. Include the track ID in the URL and the 'accept' header.

```shell
curl --request GET \
     --url https://api.ai-ark.com/api/developer-portal/v1/people/email-finder/719aba5a-876f-4690-bb57-5157153836b4/statistics \
     --header 'accept: application/json'
```

--------------------------------

### Example: Email Not Found

Source: https://docs.ai-ark.com/reference/find-emails-webhook

This JSON payload indicates that no valid email address was found for the given input. The output section details the reason for not finding an email, such as an invalid status or mailbox not found.

```json
{
  "trackId": "1c83c619-8d23-4922-8b81-ad27bf78d2b2",
  "state": "DONE",
  "description": null,
  "statistics": {
    "found": 56,
    "total": 100
  },
  "data": [
    {
      "refId": "aaa4fb3e-04cf-711a-8e6c-9a8d546240ba",
      "state": "DONE",
      "input": {
        "firstname": "Rinoy",
        "lastname": "J Vincent",
        "domain": "bizstaffingcomrade.com"
      },
      "output": [
        {
          "date": "2026-03-06T14:46:40.000145",
          "domainType": "UNKNOWN",
          "found": false,
          "generic": false,
          "status": "INVALID",
          "subStatus": "MAILBOX_NOT_FOUND",
          "mx": {
            "found": false,
            "google": false,
            "provider": null,
            "record": null
          }
        }
      ]
    }
  ]
}
```

--------------------------------

### Example: Successful Email Found

Source: https://docs.ai-ark.com/reference/find-emails-webhook

This JSON payload represents a successful webhook callback where one or more email addresses were found for the given input. It includes details about the input, the found email addresses, and their verification status.

```json
{
  "trackId": "1c83c619-8d23-4922-8b81-ad27bf78d2b2",
  "state": "DONE",
  "description": null,
  "statistics": {
    "found": 56,
    "total": 100
  },
  "data": [
    {
      "refId": "d56aea1a-6b59-2cae-68f2-95952067dbca",
      "state": "DONE",
      "input": {
        "firstname": "Rogério",
        "lastname": "Veríssimo",
        "domain": "estrelabet.com"
      },
      "output": [
        {
          "address": "rogerio.verissimo@estrelabet.com",
          "date": "2026-03-06T14:41:53.000474",
          "domainType": "SMTP",
          "found": true,
          "free": true,
          "generic": false,
          "status": "VALID",
          "subStatus": "EMPTY",
          "mx": {
            "found": false,
            "google": false,
            "provider": null,
            "record": null
          }
        }
      ]
    }
  ]
}
```

--------------------------------

### Email Finder Statistics Response

Source: https://docs.ai-ark.com/reference/get-email-finder-statistics-by-track-id

This is an example of a successful response (200 OK) from the Email Finder Statistics endpoint, showing the track ID, total and found email counts, webhook status, and job state.

```json
{
  "trackId": "719aba5a-876f-4690-bb57-5157153836b4",
  "statistics": {
    "total": 25,
    "found": 13
  },
  "webhook": {
    "state": null,
    "retry": null
  },
  "state": "PENDING",
  "description": null
}
```

--------------------------------

### Example Exported People Data

Source: https://docs.ai-ark.com/reference/export-people-webhook

This JSON object represents the data payload received from the export people webhook. It contains comprehensive details about an individual, their employment history, education, certifications, and company information. Use this structure to understand the fields available for processing.

```json
{
  "trackId": "1cf8e1d1-a597-43a9-a9aa-27ad3d905b28",
  "state": "DONE",
  "description": null,
  "statistics": {
    "found": 4,
    "total": 10
  },
  "data": [
    {
      "id": "aa38439b-af6c-028e-06e2-f981b2ea0cc3",
      "identifier": "riya-anto-k-184b84b9",
      "industry": "Human Resources",
      "last_updated": "2026-02-14",
      "summary": {
        "first_name": "Riya",
        "last_name": "Anto K",
        "full_name": "Riya Anto K",
        "headline": "Assistant General Manager Human Resources",
        "title": "Assistant General Manager Human Resources at Pandhal Global Gourmet PVT LTD",
        "picture": {
          "source": "https://images.ai-ark.com/..."
        }
      },
      "company": {
        "id": "8c1de115-4cb2-fc3d-8658-4db9267528a5",
        "summary": {
          "name": "Pandhal Global Gourmet PVT LTD",
          "industry": "food and beverage services",
          "founded_year": 1984,
          "type": "PRIVATELY_HELD",
          "staff": { "total": 63, "range": { "start": 1001, "end": 5000 } },
          "logo": { "source": "https://images.ai-ark.com/" }
        },
        "link": {
          "domain": "pandhal.in",
          "linkedin": "https://www.linkedin.com/company/pandhal-global-gourmet-pvt-ltd",
          "website": "https://www.pandhal.in"
        },
        "industries": ["food and beverage services"],
        "languages": ["english"],
        "financial": {
          "revenue": {
            "annual": { "amount": "100000-500000", "start": 100000, "end": 500000 }
          }
        },
        "location": {
          "headquarter": {
            "city": "Ernakulam",
            "country": "India",
            "state": "Kerala",
            "continent": "Asia"
          }
        }
      },
      "department": {
        "seniority": "senior",
        "departments": ["master_human_resources"],
        "functions": ["human_resources"],
        "sub_departments": ["human_resources"]
      },
      "email": {
        "state": "DONE",
        "output": [
          {
            "date": "2026-03-06T12:21:32.000523",
            "domainType": "UNKNOWN",
            "found": false,
            "generic": false,
            "status": "INVALID",
            "subStatus": "MAILBOX_NOT_FOUND",
            "mx": {
              "found": false,
              "google": false,
              "provider": null,
              "record": null
            }
          }
        ]
      },
      "certifications": [
        {
          "name": "Emotional Intelligence Trainer and Coach Programme",
          "authority": "Protouch",
          "license_number": "110535288",
          "display_source": "protouchpro.com",
          "url": "https://certificates.protouchpro.com/...",
          "company": {
            "id": "34167af6-f1c7-c088-6459-68e7342f5062",
            "name": "Protouch"
          },
          "date": { "start": "2024-07-01", "end": null }
        }
      ],
      "location": {
        "default": "Kochi, Kerala, India, Asia",
        "short": "Kochi, Kerala",
        "city": "Kochi",
        "country": "India",
        "state": "Kerala"
      },
      "link": {
        "linkedin": "https://www.linkedin.com/in/riya-anto-k-184b84b9",
        "facebook": null,
        "twitter": null,
        "github": null
      },
      "languages": {
        "primary_locale": { "country": "US", "language": "en" },
        "supported_locales": [{ "country": "US", "language": "en" }]
      },
      "member_badges": {
        "creator": true,
        "hiring": true,
        "open_to_work": false,
        "premium": false
      },
      "educations": [
        {
          "degree_name": "Advanced Human Resources Management for HR Leaders",
          "field_of_study": "Human Resources Development",
          "grade": "Completed",
          "date": { "start": "2023-06-01", "end": "2024-06-30" },
          "school": {
            "id": "691b4862-ab2e-3772-26f0-7f2e71b3ae14",
            "name": "Indian Institute of Management, Indore",
            "url": "https://www.linkedin.com/school/iimindore",
            "logo": "https://images.ai-ark.com/..."
          }
        }
      ],
      "position_groups": [
        {
          "company": {
            "id": "8c1de115-4cb2-fc3d-8658-4db9267528a5",
            "name": "Pandhal Global Gourmet PVT LTD",
            "url": "https://www.linkedin.com/company/pandhal-global-gourmet-pvt-ltd",
            "employees": { "start": 1001, "end": 5000 }
          },
          "date": { "start": "2021-09-01", "end": null },
          "profile_positions": [
            {
              "title": "Assistant General Manager Human Resources",
              "company": "Pandhal Global Gourmet PVT LTD",
              "employment_type": "Full-time"
            }
          ]
        }
      ]
    }
  ]
}
```

--------------------------------

### Get Email Finder Results by Track ID

Source: https://docs.ai-ark.com/reference/get-email-finder-results-by-track-id

Fetches paginated email finder results for a specified `trackId`. The `trackId` is obtained from a previous Find Emails by Track ID request. Pagination is controlled using `page` and `size` query parameters.

```APIDOC
## GET /api/developer-portal/v1/people/email-finder/{trackId}/inquiries

### Description
Returns paginated email finder results for a given `trackId`. The `trackId` is from the Find Emails by Track ID response. Use the `page` and `size` query parameters to paginate through results.

Each item includes a `refId`, `state`, `input` (firstname, lastname, domain), and `output` (email results with verification details).

✅ **Email Verification:** All emails (SMTP & CATCH_ALL) returned by the API are verified in real time by **BounceBan**.

### Method
GET

### Endpoint
https://api.ai-ark.com/api/developer-portal/v1/people/email-finder/{trackId}/inquiries

### Parameters
#### Path Parameters
- **trackId** (uuid) - Required - The track ID from a Find Emails by Track ID response.

#### Query Parameters
- **page** (integer) - Optional - Defaults to 0. Zero-based page index.
- **size** (integer) - Optional - Defaults to 10. Number of items per page. (1 to 100)

### Response
#### Success Response (200)
Paginated email finder inquiries results. The response body is an object containing:
- **content** (array of objects) - An array of email finder result items.
- **size** (integer) - The number of items per page.
- **totalElements** (integer) - The total number of elements across all pages.
- **pageable** (object) - Information about the pagination state.
- **last** (boolean) - Indicates if this is the last page.
- **totalPages** (integer) - The total number of pages.
- **numberOfElements** (integer) - The number of elements in the current page.
- **first** (boolean) - Indicates if this is the first page.
- **empty** (boolean) - Indicates if the response is empty.

#### Response Example
```json
{
  "content": [
    {
      "refId": "ee0bf902-00c7-deff-1fda-45bedef39602",
      "state": "DONE",
      "input": {
        "firstname": "Christopher",
        "lastname": "Sparks",
        "domain": "themetalmaniacs.com"
      },
      "output": [
        {
          "address": "csparks@themetalmaniacs.com",
          "mx": {
            "record": "mx1.example.com",
            "google": false,
            "found": true,
            "provider": "google"
          },
          "domainType": "SMTP",
          "status": "VALID",
          "subStatus": "EMPTY",
          "date": "2026-03-13T09:28:35.000779",
          "free": false,
          "generic": false,
          "found": true
        }
      ]
    }
  ],
  "size": 10,
  "totalElements": 100,
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10,
    "sort": {
      "empty": true,
      "sorted": false,
      "unsorted": true
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "last": false,
  "totalPages": 10,
  "numberOfElements": 1,
  "first": true,
  "empty": false
}
```

#### Error Response (404)
- **Description**: Track ID expired or not found.
```

--------------------------------

### Configure Cursor for AI Ark MCP

Source: https://docs.ai-ark.com/docs/mcp

Add this configuration to `~/.cursor/mcp.json` to connect Cursor to the AI Ark MCP server. Replace `{YOUR-API-KEY}` with your actual API key.

```json
{
  "mcpServers": {
    "ai-ark": {
      "url": "https://api.ai-ark.com/v1/mcp?token={YOUR-API-KEY}"
    }
  }
}
```

--------------------------------

### Create or Update a List

Source: https://docs.ai-ark.com/reference/save-list

Use this endpoint to create a new list or update an existing one. Provide a `type` and `values` to create a new list. To update, provide the list `id` and optionally specify `mode` as `APPEND` or `REPLACE`.

```json
{
  "type": "people_id",
  "values": [
    "d39d88bf-6ec5-8915-77db-3145472cf706",
    "8c83763c-efed-89ba-e651-8e66b286005e"
  ]
}
```

```json
{
  "id": "294ce93e-8881-414c-8951-e91b5df7f560",
  "type": "people_id",
  "values": [
    "d39d88bf-6ec5-8915-77db-3145472cf706",
    "8c83763c-efed-89ba-e651-8e66b286005e"
  ],
  "mode": "REPLACE"
}
```

--------------------------------

### Employee Size Range Schema

Source: https://docs.ai-ark.com/reference/company-search-1

Defines a range for employee size with start and end values. Used within the RangeWithTypeEmployeeSize schema.

```json
{
              "type": "object",
              "properties": {
                "start": {
                  "type": "number",
                  "description": "min percentage"
                },
                "end": {
                  "type": "number",
                  "description": "max percentage"
                },
                "timeFrame": {
                  "$ref": "#/components/schemas/TimeFrameEnum",
                  "description": "Number of months"
                }
              }
            }
```

--------------------------------

### Create or Update a List

Source: https://docs.ai-ark.com/reference/save-list

This endpoint allows you to create a new list or update an existing one. If no `id` is provided, a new list is created. If an `id` is provided and belongs to the current workspace, the list is updated. Otherwise, a new list is created. Lists are typed and can contain either `people_id` or `company_id`.

```APIDOC
## POST /v1/lists

### Description
Build reusable lists of people or companies, then reference them from People Search and Company Search to <strong>exclude</strong> matches — handy for skipping prospects you already contacted or accounts you want to avoid. You can keep up to <strong>50 lists per day</strong>. Each list can grow up to <strong>10,000 items</strong> by appending more values, or you can replace it with a fresh set, so the same list stays useful across many searches during the day. Lists expire automatically after 24 hours.

### Method
POST

### Endpoint
/v1/lists

### Parameters
#### Request Body
- **id** (string) - Optional - Optional. If provided and owned by the current workspace, the list is updated; otherwise a new list is created.
- **type** (string) - Required - Required when creating a new list. Ignored when updating an existing owned list. Enum: `people_id`, `company_id`.
- **values** (array) - Required - Identifiers to store. Max 10,000 items per list.
  - items (string)
- **mode** (string) - Optional - Only used when updating an existing list. `APPEND` merges; `REPLACE` overwrites. Default: `APPEND`. Enum: `APPEND`, `REPLACE`.

### Request Example
```json
{
  "type": "people_id",
  "values": [
    "d39d88bf-6ec5-8915-77db-3145472cf706",
    "8c83763c-efed-89ba-e651-8e66b286005e"
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - List identifier.
- **workspace** (string)
- **type** (string)
- **values** (array) - Identifiers stored in the list.
  - items (string)
- **created** (integer) - Epoch milliseconds at creation time.

#### Response Example
```json
{
  "id": "294ce93e-8881-414c-8951-e91b5df7f560",
  "workspace": "your-workspace-id",
  "type": "people_id",
  "values": [
    "d39d88bf-6ec5-8915-77db-3145472cf706",
    "8c83763c-efed-89ba-e651-8e66b286005e"
  ],
  "created": 1778064460905
}
```
```

--------------------------------

### Simplified Export People Webhook Payload

Source: https://docs.ai-ark.com/reference/export-people-webhook

This is a simplified example of the data structure sent by the export people webhook. It includes location and date information for events.

```json
{
  "location": "Kochi, Kerala, India",
  "date": { "start": "2024-09-01", "end": null }
}
]
}
]
}
]
}
```

--------------------------------

### Successful Reverse People Lookup Response

Source: https://docs.ai-ark.com/reference/people-reverse-lookup

This is an example of a successful response (200 OK) from the Reverse People Lookup API, containing the found person's profile information.

```json
{
  "id": "5f8583f4-e970-4efa-c429-f4c63a4cd2cf",
  "identifier": "bennorrisub",
  "profile": {
    "first_name": "Benjamin",
    "last_name": "Norris",
    "full_name": "Benjamin Norris",
    "headline": "School District Data Coordinator for the Central New York Regional Information Center",
    "title": "School District Data Coordinator",
    "picture": {
      "source": "https://s3.ai-ark.com/ark-person/images/5f8583f4-e970-4efa-c429-f4c63a4cd2cf.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20251021T102845Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=HC2GZVQFT79BXWGX0GP2%2F20251021%2Fai-ark%2Fs3%2Faws4_request&X-Amz-Signature=0fedcb24b53b4775a137a028c762930d851abafff5c93ceb8f1558245bac8eb7"
    },
    "background": {
      "source": "https://media.licdn.com/dms/image/v2/C4E16AQFXEpltv0W3aA/profile-displaybackgroundimage-shrink_200_800/profile-displaybackgroundimage-shrink_200_800/0/1631321640721?e=1756944000&v=beta&t=hTM66u5gRjPTsJ4DbMVV3JamCtHMkDpUNMscxUqnixs"
    },
    "birth_date": "1600-09-24",
    "summary": null
  },
  "link": {
    "linkedin": "https://www.linkedin.com/in/bennorrisub",
    "twitter": null,
    "github": null,
    "facebook": null
  },
  "location": {
    "country": "United States",
    "state": "New York",
    "city": "Syracuse",
    "position": null,
    "default": "Syracuse, New York, United States, North America",
    "short": "Syracuse, New York"
  },
  "languages": {
    "primary_locale": {
      "country": "US",
      "language": "en"
    }
  }
}
```

--------------------------------

### Fetch Your Credit

Source: https://docs.ai-ark.com/reference/fetch-credit

Retrieves the number of remaining credits in your account.

```APIDOC
## Fetch Your Credit

### Description
Retrieves the number of remaining credits in your account.

### Method
GET

### Endpoint
https://api.ai-ark.com/api/developer-portal/v1/payments/credits

### Request Headers
- `Content-Type: application/json`
- `accept: application/json`

### Response
#### Success Response (200)
- **total** (integer) - Number of remaining credits in your account.

### Response Example
```json
{
  "total": 100
}
```
```

--------------------------------

### Python Authentication with Requests

Source: https://docs.ai-ark.com/docs/authentication

Use the 'requests' library in Python to send authenticated POST requests. Ensure the 'X-TOKEN' header is set with your API key.

```Python
import requests

api_key = 'YOUR_API_KEY'
url = 'https://api.ai-ark.com/api/developer-portal/v1/companies'

headers = {
    'X-TOKEN': api_key,
    'content-type': 'application/json'
}
payload = {}
response = requests.post(url, headers=headers, json=payload)
data = response.json()

print(data)
```

--------------------------------

### Successful Mobile Phone Finder API Response

Source: https://docs.ai-ark.com/reference/people-mobile-phone-finder

This is an example of a successful response from the Mobile Phone Finder API. It includes an ID for the request and an array containing the found phone number(s).

```json
{
  "id": "daaab0f8-bbf1-1383-9167-b8825b1fab85",
  "linkedin": "https://www.linkedin.com/in/melissa-deyneka-51116125",
  "data": [
    [
      "+13152468945"
    ]
  ]
}
```

--------------------------------

### cURL Authentication

Source: https://docs.ai-ark.com/docs/authentication

Authenticate cURL requests by passing the 'X-TOKEN' header and the request body.

```bash
curl -H "X-TOKEN: YOUR_API_KEY" -d "{}" "https://api.ai-ark.com/api/developer-portal/v1/companies" 
```

--------------------------------

### Get Email Finder Statistics by Track ID

Source: https://docs.ai-ark.com/reference/get-email-finder-statistics-by-track-id

Returns email-finding statistics for a given `trackId`. The `trackId` is from the Find Emails by Track ID endpoint. Use this endpoint to poll progress (e.g. `statistics.total`, `statistics.found`) and state until the job completes.

```APIDOC
## GET /api/developer-portal/v1/people/email-finder/{trackId}/statistics

### Description
Returns email-finding statistics for a given `trackId`. The `trackId` is from the Find Emails by Track ID endpoint. Use this endpoint to poll progress (e.g. `statistics.total`, `statistics.found`) and state until the job completes.

### Method
GET

### Endpoint
https://api.ai-ark.com/api/developer-portal/v1/people/email-finder/{trackId}/statistics

### Parameters
#### Path Parameters
- **trackId** (uuid) - Required - The track ID from a Find Emails by Track ID response.

### Request Example
```bash
curl --request GET \
     --url https://api.ai-ark.com/api/developer-portal/v1/people/email-finder/719aba5a-876f-4690-bb57-5157153836b4/statistics \
     --header 'accept: application/json'
```

### Response
#### Success Response (200)
- **trackId** (uuid) - The unique identifier for the email finding track.
- **statistics** (object) - An object containing email finding statistics.
  - **total** (integer) - The total number of emails processed.
  - **found** (integer) - The total number of emails found.
- **webhook** (object) - Information about webhook status.
  - **state** (string | null) - The state of the webhook.
  - **retry** (string | null) - Information about webhook retries.
- **state** (string) - The current state of the email finding job (e.g., PENDING, PROCESSING, COMPLETED).
- **description** (string | null) - A description of the current state or any errors.

#### Response Example
```json
{
  "trackId": "719aba5a-876f-4690-bb57-5157153836b4",
  "statistics": {
    "total": 25,
    "found": 13
  },
  "webhook": {
    "state": null,
    "retry": null
  },
  "state": "PENDING",
  "description": null
}
```

#### Error Response (404)
- **Error**: Track ID not found or expired.
```