> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# עימוד

> סריקת רשימות ב-Living Security Public API באמצעות מעטפת הרשימה, הפרמטר limit ומצביעי page_token אטומים.

כל נקודת קצה של רשימה ב-`/v1` מחזירה את אותה מעטפת ומבצעת עימוד
באותו אופן: מבוסס אסימון, קדימה בלבד.

## מעטפת הרשימה

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "ent_8f3d2c1b0a9e",
      "object": "entity",
      "type": "person",
      "status": "active",
      "display_name": "Dana Rivera",
      "email": "dana.rivera@example.com",
      "created_at": "2025-11-03T09:21:44.000Z",
      "updated_at": "2026-07-28T16:02:10.000Z"
    }
  ],
  "next_page_token": "eyJvcmdhbml6YXRpb2...",
  "has_more": true
}
```

<ResponseField name="object" type="string">
  תמיד `"list"`.
</ResponseField>

<ResponseField name="data" type="array">
  עמוד המשאבים, בסדר יציב ודטרמיניסטי.
</ResponseField>

<ResponseField name="next_page_token" type="string | null">
  יש להעביר ערך זה בתור `page_token` בבקשה הבאה כדי לאחזר את העמוד הבא.
  `null` כאשר אין עוד תוצאות.
</ResponseField>

<ResponseField name="has_more" type="boolean">
  האם קיימות תוצאות נוספות מעבר לעמוד זה.
</ResponseField>

## פרמטרים של הבקשה

<ParamField query="limit" type="integer" default="25">
  גודל העמוד. מספר שלם בין 1 ל-500. ערכים מחוץ לטווח זה גורמים להחזרת
  `400` עם הקוד `invalid_request`.
</ParamField>

<ParamField query="page_token" type="string">
  הערך `next_page_token` מהתגובה הקודמת. יש להשמיט אותו בעמוד הראשון.
</ParamField>

אין פרמטרים של היסט (offset), אין מעבר לעמוד הקודם ואין ספירות כוללות מדויקות. כדי לספור אוסף, יש לסרוק אותו.

<Note>
  **חריגה:** `GET /v1/cohorts/{id}/members` מחזיר לכל היותר 50 שורות בכל
  עמוד, גם אם מבקשים `limit` גבוה יותר. `has_more` ו-
  `next_page_token` ממשיכים לשקף את יתרת הקבוצה האמיתית.
</Note>

יש לבצע אימות באחד משני סוגי האישורים של Basic — ראו
[Quickstart](/he/developers/v1/quickstart) (`apikey:secret` או `secret:`).
יש להגדיר את `BASE` למארח האזורי של הארגון — ראו
[Regions](/he/developers/v1/regions).

## סריקת רשימה

יש לטעון את `LIVING_SECURITY_API_KEY` ממנהל הסודות שלכם, כפי שמוצג ב-quickstart.
דוגמה זו דורשת `entity:read`; ייתכן שהמפתח ששימש במדריך הבקשה הראשונה
יזדקק להענקה נוספת זו. יש להתקין את `requests` עבור Python או `jq` עבור
דוגמת ה-shell. בשתי הדוגמאות מצוינת גרסה מקובעת, המסננים נשארים ללא שינוי, וניתובים מחדש נדחים.
הן נעצרות בשגיאות ולאחר 1,000 עמודים, ואינן מדווחות על סריקה
חלקית כעל סריקה שהושלמה. זמן הקריאה (read timeout) ב-Python מגביל חוסר פעילות, ולא את
משך העבודה הכולל; יש להגדיר מועד סיום לעבודה באינטגרציה שלכם.

יש לבקש עמודים עד ש-`next_page_token` הוא `null`. מומלץ להעדיף `limit=500` בקריאות
בכמות גדולה, כדי לכסות את האוסף בפחות בקשות — ראו
[מגבלות קצב](/he/developers/v1/rate-limits).

<CodeGroup>
  ```bash cURL + jq theme={null}
  set -euo pipefail
  # US: BASE="https://api.us-east-1.livingsecurity.ai/v1"
  BASE="https://api.eu-west-1.livingsecurity.ai/v1"
  : "${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}"
  TOKEN=""

  # Bound each run. Increase this page budget deliberately for larger collections.
  for ((page_number=1; page_number<=1000; page_number++)); do
    PARAMS=(--data-urlencode "limit=500" --data-urlencode "type=person")
    if [ -n "$TOKEN" ]; then
      PARAMS+=(--data-urlencode "page_token=$TOKEN")
    fi
    RESULT=$(curl --silent --show-error --fail-with-body \
      --connect-timeout 5 --max-time 30 --get \
      -u "apikey:$LIVING_SECURITY_API_KEY" \
      -H "Living-Security-Version: 2026-07-01" \
      --write-out '\n%{http_code}' "${PARAMS[@]}" "$BASE/entities")
    STATUS="${RESULT##*$'\n'}"
    PAGE="${RESULT%$'\n'*}"
    [ "$STATUS" = "200" ] || { echo "Unexpected HTTP status: $STATUS" >&2; exit 1; }
    jq -e 'has("next_page_token") and .object == "list" and (.data | type == "array") and
      ((.has_more == false and .next_page_token == null) or
       (.has_more == true and (.next_page_token | type == "string" and length > 0)))' \
      <<< "$PAGE" > /dev/null
    NEXT=$(jq -r '.next_page_token // empty' <<< "$PAGE")
    [ -z "$NEXT" ] || [ "$NEXT" != "$TOKEN" ] || { echo "Repeated page token" >&2; exit 1; }
    jq -r '.data[].id' <<< "$PAGE"
    [ -n "$NEXT" ] || exit 0
    TOKEN="$NEXT"
  done
  echo "Page budget exhausted; the collection is incomplete" >&2
  exit 1
  ```

  ```python Python theme={null}
  import os
  import requests

  # US: BASE = "https://api.us-east-1.livingsecurity.ai/v1"
  BASE = "https://api.eu-west-1.livingsecurity.ai/v1"
  AUTH = ("apikey", os.environ["LIVING_SECURITY_API_KEY"])

  def iter_entities(*, entity_type="person", max_pages=1000):
      if type(max_pages) is not int or max_pages < 1:
          raise ValueError("max_pages must be a positive integer")
      params = {"limit": 500, "type": entity_type}
      for _ in range(max_pages):
          response = requests.get(
              f"{BASE}/entities",
              auth=AUTH,
              params=params,
              headers={"Living-Security-Version": "2026-07-01"},
              timeout=(5, 30),
              allow_redirects=False,
          )
          try:
              response.raise_for_status()
              if response.status_code != 200:
                  raise RuntimeError("Unexpected response; check your regional API URL")
              page = response.json()
          finally:
              response.close()
          if (not isinstance(page, dict) or page.get("object") != "list"
                  or not isinstance(page.get("data"), list)
                  or type(page.get("has_more")) is not bool
                  or "next_page_token" not in page):
              raise RuntimeError("Invalid list response")
          token = page["next_page_token"]
          if ((page["has_more"] and (not isinstance(token, str) or not token))
                  or (not page["has_more"] and token is not None)):
              raise RuntimeError("Inconsistent list response")
          if token is not None and token == params.get("page_token"):
              raise RuntimeError("Repeated page token")
          yield from page["data"]
          if token is None:
              return
          params = {**params, "page_token": token}
      raise RuntimeError("Page budget exhausted; the collection is incomplete")

  if __name__ == "__main__":
      for entity in iter_entities():
          print(entity["id"])
  ```
</CodeGroup>

## שמירה על מסננים יציבים במהלך העימוד

אסימוני עמוד הם מצביעים אטומים וחתומים. כל אסימון קשור
לארגון, לחשבון השירות המאומת, לגרסת החוזה ולקבוצת המסננים המדויקת של הבקשה שיצרה אותו. שינוי של כל אחד מאלה באמצע הסריקה — לדוגמה,
הוספת מסנן `type` בעמוד השני — מחזיר `400` עם הקוד
`invalid_request` על הפרמטר `page_token`:

```json 400 Invalid request theme={null}
{
  "type": "https://docs.livingsecurity.com/developers/v1/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "page_token does not match this request's organization, credential, contract version, or filters.",
  "code": "invalid_request",
  "param": "page_token",
  "request_id": "req_...",
  "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/invalid_request",
  "retryable": false
}
```

כדי לשנות מסננים, יש להתחיל סריקה חדשה מהעמוד הראשון.

<Tip>
  יש להתייחס אל `page_token` כאל מחרוזת אטומה: יש להחזיר אותו בדיוק כפי שהתקבל.
  אין לפענח אסימונים, לאחסן אותם לטווח ארוך או לבנות אותם — הפורמט הפנימי שלהם
  עשוי להשתנות בכל עת וללא הודעה מראש.
</Tip>

<Note>
  נקודות קצה של רשימות דוחות פרמטרי שאילתה שאינם נתמכים באמצעות `400`
  `invalid_request` שמציין את שם הפרמטר. יש לעיין במסמך העזר של כל נקודת קצה כדי לראות אילו
  מסננים נתמכים בה.
</Note>

## טיפול באוסף שנקטע או משתנה

דוגמאות אלה אינן מנסות שוב באופן אוטומטי לאחר שגיאות. עבור `429`, יש לכבד את `Retry-After`
ולפעול לפי [הנחיות הניסיון החוזר](/he/developers/v1/rate-limits) המוגבלות. בעת ניסיון חוזר של קריאה, יש לשמור על אותו
אזור, אותו חשבון שירות, אותה גרסה, אותם מסננים ואותו אסימון עמוד
שעובד בהצלחה לאחרונה. החלפת אישורים אינה מעניקה גישה:
כל בקשה עדיין בודקת את ההרשאות הנוכחיות.

קריאה מרובת עמודים אינה תמונת מצב של האוסף. שורות עשויות להשתנות בזמן
שאתם עוברים עליו. יש לעבד משאבים לפי `id` היציב שלהם ולהפוך כתיבות במורד הזרם
לאידמפוטנטיות; הפעלה מחדש עשויה להחזיר שורה שוב. אם אסימון נדחה,
יש לבדוק את שגיאת `page_token` ולתקן את הבקשה לפני שמתחילים מחדש
מהעמוד הראשון. אין להשליך בשקט נתונים שכבר עובדו ואין לסמן
ייצוא שנקטע כהושלם. לקבלת סכומים מדויקים לצורכי דיווח, יש להשתמש במשאב הדיווח המתאים
ולא להתייחס לסריקת רשימה חיה כאל תמונת מצב.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.