Docs · Concepts
Paging
Searches return a page of results at a time, with a cursor for the next. Each page is charged for what's on it, so you choose how far to go.
Preview
This is how the API is planned to work. Names and fields may change before launch. The APIs are in early access: join early access to get a key when they're ready.
The next cursor
Each page of results comes with next. Send it back as cursor, with the same filters, to get the following page. On the last page, next is null.
{
"companies": [
{
"name": "Example Freight Ltd",
"domain": "examplefreight.example",
"company_url": "https://profiles.example/company/example-freight",
"industry": "Truck Transportation",
"headcount": "51-200",
"employees": 140,
"hq": "Leeds",
"country": "GB"
}
],
"next": "cur_25",
"total": 240,
"coverage": "full"
}Treat the cursor as an opaque string: store it or pass it on as it is, without reading anything into it.
Page size
Set limit to anything from 1 to 100 companies a page. Anything else gets a 400. People search pages through a search's results the same way, with cursor and limit on GET /people/searches/{id}.
A page can hold fewer than you asked for, such as when your credits run short. Carry on while there's a next.
Fetching several pages
Every company on a page is charged (see Credits and prices), so set a limit on pages and stop once you have enough.
async function searchAll(filters, maxPages = 4) {
const companies = [];
let cursor;
for (let page = 0; page < maxPages; page++) {
const res = await fetch("https://api.magpie-cloud.com/v1/companies/search", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MAGPIE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ ...filters, limit: 100, ...(cursor ? { cursor } : {}) }),
});
if (!res.ok) throw new Error(`Search failed: ${res.status}`);
const data = await res.json();
companies.push(...data.companies);
if (!data.next) break; // the last page
cursor = data.next;
}
return companies;
}import os
import requests
def search_all(filters, max_pages=4):
companies = []
cursor = None
for _ in range(max_pages):
body = {**filters, "limit": 100}
if cursor:
body["cursor"] = cursor
res = requests.post(
"https://api.magpie-cloud.com/v1/companies/search",
json=body,
headers={"Authorization": f"Bearer {os.environ['MAGPIE_API_KEY']}"},
timeout=90,
)
res.raise_for_status()
data = res.json()
companies.extend(data["companies"])
if not data["next"]:
break # the last page
cursor = data["next"]
return companiesQuestions about the APIs? Email pele@magpiecrm.com.