Read entities

Use the FLOW_API_URL, FLOW_CUSTOMER, and FLOW_API_KEY variables from the quickstart. cURL examples use Bash and jq. Python uses requests; JavaScript uses Node.js 22 or later with .mjs files.

Find your project

curl --fail-with-body --silent --show-error \
  "$FLOW_API_URL/project" \
  -H "X-API-Key: $FLOW_API_KEY" \
  -H "customer: $FLOW_CUSTOMER" \
  | jq '.[] | {id, name, slug}'

import os
import json
import requests

base_url = os.environ["FLOW_API_URL"].rstrip("/")
headers = {"X-API-Key": os.environ["FLOW_API_KEY"], "customer": os.environ["FLOW_CUSTOMER"]}

response = requests.get(
    f"{base_url}/project", headers=headers, timeout=30
)
response.raise_for_status()
data = response.json()
for project in data:
    print(json.dumps({key: project[key] for key in ("id", "name", "slug")}))

const baseUrl = process.env.FLOW_API_URL.replace(/\/$/, "");
const headers = {
  "X-API-Key": process.env.FLOW_API_KEY,
  customer: process.env.FLOW_CUSTOMER,
};

const url = new URL(`${baseUrl}/project`);
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const data = await response.json();
for (const { id, name, slug } of data) console.log({ id, name, slug });

Set PROJECT_ID to the id of the project you want to read. The project list returns an array; project-scoped endpoints take the ID in the URL.

export PROJECT_ID="your-project-id"

Discover categories and fields

curl --fail-with-body --silent --show-error \
  "$FLOW_API_URL/project/$PROJECT_ID/data-model" \
  -H "X-API-Key: $FLOW_API_KEY" \
  -H "customer: $FLOW_CUSTOMER" \
  | jq '.[] | {id, name, fields}'

import os
import json
import requests

base_url = os.environ["FLOW_API_URL"].rstrip("/")
headers = {"X-API-Key": os.environ["FLOW_API_KEY"], "customer": os.environ["FLOW_CUSTOMER"]}

response = requests.get(
    f"{base_url}/project/{os.environ['PROJECT_ID']}/data-model", headers=headers, timeout=30
)
response.raise_for_status()
data = response.json()
for category in data:
    print(json.dumps({key: category[key] for key in ("id", "name", "fields")}))

const baseUrl = process.env.FLOW_API_URL.replace(/\/$/, "");
const headers = {
  "X-API-Key": process.env.FLOW_API_KEY,
  customer: process.env.FLOW_CUSTOMER,
};

const url = new URL(`${baseUrl}/project/${process.env.PROJECT_ID}/data-model`);
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const data = await response.json();
for (const { id, name, fields } of data) console.log({ id, name, fields });

Each category contains fields with a key, name, and type. Use the category’s id as entity_type when filtering entities, and use field keys to interpret their values map. Discover these values in the selected project before reading or writing custom fields.

Read a page

curl --fail-with-body --silent --show-error --get \
  "$FLOW_API_URL/project/$PROJECT_ID/entities" \
  -H "X-API-Key: $FLOW_API_KEY" \
  -H "customer: $FLOW_CUSTOMER" \
  --data-urlencode "branch_id=master" \
  --data-urlencode "starting_after=0" \
  --data-urlencode "limit=100"

import os
import json
import requests

base_url = os.environ["FLOW_API_URL"].rstrip("/")
headers = {"X-API-Key": os.environ["FLOW_API_KEY"], "customer": os.environ["FLOW_CUSTOMER"]}

response = requests.get(
    f"{base_url}/project/{os.environ['PROJECT_ID']}/entities", headers=headers, timeout=30,
    params={"branch_id": "master", "starting_after": "0", "limit": 100}
)
response.raise_for_status()
data = response.json()
print(json.dumps(data, indent=2))

const baseUrl = process.env.FLOW_API_URL.replace(/\/$/, "");
const headers = {
  "X-API-Key": process.env.FLOW_API_KEY,
  customer: process.env.FLOW_CUSTOMER,
};

const url = new URL(`${baseUrl}/project/${process.env.PROJECT_ID}/entities`);
url.search = new URLSearchParams({ branch_id: "master", starting_after: "0", limit: "100" }).toString();
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const data = await response.json();
console.log(JSON.stringify(data, null, 2));

The response contains items, nextPageStart, and moreAvailable. Each item includes an entity id and a values object. For example, read its name from values.name. To filter by category, add the entity_type query parameter with a category ID from the data model. To read another branch, replace master with its branch ID. The entity list supports entity_type and branch_id selection. For bounded name, field-value, or exact-ID lookup, use GET /project/{projectId}/entities/search with query, optional branch_id and entity_type, and a limit of at most 100. Search returns compact matches; fetch an entity by ID when you need full values and links. Search is not a paginated export. For structured conditions, use POST /project/{projectId}/entities/filter/query. Its JSON filter supports category and typed field conditions combined in AND/OR groups. Send branch_id in the body to select a branch. The response contains matching IDs, without hierarchy or a total count; continue with its opaque next_cursor until it is null, even after an empty page. The pages reflect current state rather than a frozen snapshot, so restart if the filter or data model changes. See the endpoint reference for supported operators and response schemas.

Read all pages

Each example prints one JSON object per entity. It uses a page size of 100 and reads Base. Add the same entity_type parameter to every request if you need a category filter.

set -euo pipefail
cursor=0

while true; do
  page=$(curl --fail-with-body --silent --show-error --get \
    "$FLOW_API_URL/project/$PROJECT_ID/entities" \
    -H "X-API-Key: $FLOW_API_KEY" \
    -H "customer: $FLOW_CUSTOMER" \
    --data-urlencode "branch_id=master" \
    --data-urlencode "starting_after=$cursor" \
    --data-urlencode "limit=100")

  jq -c '.items[]' <<< "$page"
  more=$(jq -r '.moreAvailable' <<< "$page")
  [[ "$more" == "true" ]] || break
  cursor=$(jq -er '.nextPageStart' <<< "$page")
done

import os
import json
import requests

base_url = os.environ["FLOW_API_URL"].rstrip("/")
headers = {"X-API-Key": os.environ["FLOW_API_KEY"], "customer": os.environ["FLOW_CUSTOMER"]}

cursor = "0"
while True:
    response = requests.get(
        f"{base_url}/project/{os.environ['PROJECT_ID']}/entities",
        headers=headers, timeout=30,
        params={"branch_id": "master", "starting_after": cursor, "limit": 100}
    )
    response.raise_for_status()
    page = response.json()
    for entity in page["items"]:
        print(json.dumps(entity))
    if not page["moreAvailable"]:
        break
    cursor = page["nextPageStart"]
    if cursor is None:
        raise ValueError("Missing nextPageStart on an incomplete page")

const baseUrl = process.env.FLOW_API_URL.replace(/\/$/, "");
const headers = {
  "X-API-Key": process.env.FLOW_API_KEY,
  customer: process.env.FLOW_CUSTOMER,
};

let cursor = "0";
while (true) {
  const url = new URL(`${baseUrl}/project/${process.env.PROJECT_ID}/entities`);
  url.search = new URLSearchParams({
    branch_id: "master", starting_after: cursor, limit: "100",
  }).toString();
  const response = await fetch(url, { headers, signal: AbortSignal.timeout(30_000) });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  const page = await response.json();
  for (const entity of page.items) console.log(JSON.stringify(entity));
  if (!page.moreAvailable) break;
  cursor = page.nextPageStart;
  if (cursor == null) throw new Error("Missing nextPageStart on an incomplete page");
}

Continue based on moreAvailable, even when items is empty. Pass nextPageStart unchanged; do not increment it or infer it from an entity ID.

Quickstart

Automations

Flow MCP

Endpoints

Read entities

Find your project

Discover categories and fields

Read a page

Read all pages

​Find your project

​Discover categories and fields

​Read a page

​Read all pages

Find your project

Discover categories and fields

Read a page

Read all pages