LordTracker customer API

API access requires Pro, Server Bundle or an active 7-day Pro trial. It follows the auto-sync entitlement. Small and lapsed workspaces receive a 403 error with a billing link. Owners and managers can create and revoke keys from API access in alliance settings or workspace settings.

New keys start with tl_live_ and contain 32 random base64url characters. Copy the full key when it is created; it is shown once. Send it in the Authorization header. Keep it on your server or in a private integration.

Authorization: Bearer tl_live_<your-key>

Alliance keys read only their alliance. Workspace keys read active alliances in that workspace (provide ?allianceId=<internal-id>) and its kingdom's public data. Kingdom endpoints reject alliance keys. Revoked, expired and out-of-scope keys fail immediately; keys also stop working if their creator loses manager access.

Read endpoints use GET. Import endpoints use POST and require a Read and write alliance key. Keys default to Read only; workspace keys stay read-only. Changing scope requires a new key. IDs are internal LordTracker IDs. The roster includes a game Lord ID only when available to managers in the signed-in app; public kingdom data never includes game IDs. Emails, website user links, notes, absences, aliases and private settings are omitted.

Responses use { "data": [...], "meta": { "limit": 100, "hasNextPage": false, "nextCursor": null } }. The default limit is 100 and the cap is 200. Pass ?cursor=<nextCursor> for the next page and keep the same endpoint, scope and filters. Cursors follow stable row keys; live updates can change rankings and standings between requests.

JSON is the default. Use Accept: text/csv or ?format=csv for CSV; an explicit format=json overrides Accept. CSV uses one row per entry and flattens nested readings into dotted column names. Missing cells are empty. Pagination and coverage are in X-Next-Cursor, X-Has-Next-Page and X-API-Meta headers. Spreadsheet formula prefixes are escaped.

Each key allows 60 successful requests per rolling minute and 5,000 per rolling 24 hours. Responses after the rate check include X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Day and X-RateLimit-Remaining-Day. A 429 includes Retry-After in seconds. Remaining counts describe availability before the current request.

Request logs retain only the key reference, route template, status, duration and time for 30 days. They never store bodies, query strings or raw keys. Like the source API, this API does not grant cross-origin browser access; use a server-side integration.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" -H "Accept: text/csv" \
  "https://www.lordtracker.com/api/v1/alliance/lords?limit=200"

Power, kills, hero power, Castle level, VS and donations use decimal strings to preserve precision. Missing values stay null; zero is an observed zero. Readings carry their own ISO 8601 UTC observation date. Roles have a separate observation date.

History is newest first and accepts inclusive from and to dates or timestamps. A date-only boundary means UTC midnight; use a full end timestamp to include an entire final day. Metric history can be narrowed with memberId.

VS, donations and performance accept a Monday week=YYYY-MM-DD, defaulting to the current configured week. Responses return weekStart as UTC midnight plus the recorded reset hour. VS daily scores and the recorded weekly total are independent. Donation totals are reviewed weekly values, never live counters. Performance uses the app's evaluator and weighted standings; excused grades are shown as ungraded to keep absences private, and targets, weights and reasons are omitted.

Kingdom rankings are bounded captures, usually PARTIAL. A missing row does not mean zero or departure. Ranking metadata includes capture time, status, ranking limit and captured count. Public history is restricted to the latest 1,500 observations; meta.truncated reports that bound.

Ranking types: alliances — 1 kills, 2 power; Lords — 3 kills, 4 power, 5 Lord level, 13 hero power, 14 PvE stage, 15 highest hero power. Castle level is a roster reading and is separate from Lord level.

{
  "error": {
    "code": "AUTO_SYNC_REQUIRED",
    "message": "Public API access requires Pro, Server Bundle or an active Pro trial. Upgrade in Billing.",
    "details": {
      "billingUrl": "/billing?workspace=workspace_id"
    }
  }
}

Switch on error.code. 400: VALIDATION_ERROR (dates, week, cursor, limit or ranking). 401: UNAUTHENTICATED, INVALID_KEY, KEY_REVOKED, KEY_EXPIRED. 403: INVALID_SCOPE, TENANT_MISMATCH, AUTO_SYNC_REQUIRED, TRIAL_EXPIRED, FORBIDDEN. 404: MEMBER_NOT_FOUND, PLAYER_NOT_FOUND, EVENT_NOT_FOUND. 409: REQUEST_CONFLICT. 413: LIMIT_EXCEEDED (body size). 415: UNSUPPORTED_FORMAT. 422: VALIDATION_ERROR with per-row MEMBER_NOT_FOUND, AMBIGUOUS_MEMBER, INVALID_MEMBER or DUPLICATE_ENTRY details. 429: RATE_LIMITED. 500: INTERNAL_ERROR. Details are optional. Unsupported methods receive 405.

Owners and managers can create a Read and write key in alliance Settings → API access. It can read and import only that alliance. Workspace keys remain read-only. Writes and successful retries use the same rate limits and request log as reads.

POST application/json with an entries array, or text/csv with a header row. CSV request context, such as week or runId, goes in query parameters. Bodies are limited to 400 KB and 2,500 rows; donations allow 500 totals, VS allows 1,000 daily/weekly values and battles allow 400 rows.

Identify each Lord by memberId (LordTracker roster ID), gameLordId or an exact unique name. Explicit IDs take precedence over names. The API never creates Lords; add or review them in Members first. Unknown or ambiguous identities fail per row. Send exact integer strings, or safe JSON integers, up to 30 digits. Send "0" for an observed zero. Missing readings stay missing; blank metric, VS grid and donation rows are skipped, and a request needs at least one recorded value. Unspecified event and battle fields preserve existing readings.

Every request is all-or-nothing. Validation returns the source API's error.code, error.message and optional error.details envelope. Row failures include details.errors with a one-based data row number, code and message. CSV row 1 is the first row after its header.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "1 rows failed validation. No data changed.",
    "details": {
      "errors": [
        {
          "row": 2,
          "code": "AMBIGUOUS_MEMBER",
          "message": "More than one Lord matches. Send an ID."
        }
      ]
    }
  }
}

Set Idempotency-Key to a unique identifier for each upload (1–200 printable ASCII characters without spaces). An identical retry returns the original JSON result. Keep the body bytes, endpoint, query and Content-Type identical; reusing a key for a different request returns 409 REQUEST_CONFLICT. Without this header each request is a new import. Failed requests leave no receipt and can be corrected and retried.

A successful upload appears as one activity batch, such as API import · Lord power · 24 rows · key 'Sheets'. Owners and managers can undo it in Activity log within 24 hours while its records remain unchanged. Later edits or dependent readings block undo. A retry after undo still returns the original result and does not restore undone data; a deliberate replacement needs a new Idempotency-Key. Hero power may be held for officer review under the same anomaly rules as browser imports.

{
  "data": {
    "batchId": "batch_id",
    "activityId": "activity_id",
    "rowCount": 24,
    "quarantined": 0
  }
}

Dated Lord power readings. observedAt (or recordedAt) is required per row or request; future dates fail. Missing values are skipped.

curl -X POST -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: sheets-lord-power-2026-10-05' \
  --data '{"observedAt":"2026-10-05T18:00:00Z","entries":[{"gameLordId":"801234567","power":"126540800"}]}' \
  'https://www.lordtracker.com/api/v1/alliance/lords/power'

CSV body (send request context in query parameters):

gameLordId,power,observedAt
801234567,126540800,2026-10-05T18:00:00Z

Dated cumulative kill readings. Each reading retains its observation time; kill gains do not establish participation.

curl -X POST -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: sheets-lord-kills-2026-10-05' \
  --data '{"observedAt":"2026-10-05T18:00:00Z","entries":[{"memberId":"member_id","kills":"843251"}]}' \
  'https://www.lordtracker.com/api/v1/alliance/lords/kills'

CSV body (send request context in query parameters):

memberId,kills,observedAt
member_id,843251,2026-10-05T18:00:00Z

Dated total hero power readings. Uses the browser import's anomaly quarantine; quarantined rows are counted in the response and await officer review.

curl -X POST -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: sheets-hero-power-2026-10-05' \
  --data '{"observedAt":"2026-10-05T18:00:00Z","entries":[{"memberId":"member_id","heroPower":"48125300"}]}' \
  'https://www.lordtracker.com/api/v1/alliance/lords/hero-power'

CSV body (send request context in query parameters):

memberId,heroPower,observedAt
member_id,48125300,2026-10-05T18:00:00Z

week (or weekStart) is a Monday YYYY-MM-DD. day is zero-based and must be configured. Daily score/day and weeklyTotal write separate records; no totals are inferred. Grid fields day1–day7 use one-based labels. Alternatively use score/scoredOn (date or ISO timestamp), separately from grid/weekly rows. Stored week reset/day rules take precedence over current settings.

curl -X POST -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: sheets-vs-scores-2026-10-05' \
  --data '{"week":"2026-10-05","entries":[{"memberId":"member_id","day":0,"score":"6400000","weeklyTotal":"25000000"}]}' \
  'https://www.lordtracker.com/api/v1/alliance/lords/vs'

CSV body (send request context in query parameters):

memberId,day1,day2,weeklyTotal
member_id,6400000,,25000000

Final weekly totals only. week (or weekStart) is a Monday YYYY-MM-DD. todayProgress, weeklyProgress, counterSampleId, confirmLiveCounter and other live-counter fields are rejected. Missing totals are skipped.

curl -X POST -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: sheets-weekly-donations-2026-10-05' \
  --data '{"week":"2026-10-05","entries":[{"memberId":"member_id","total":"2800"}]}' \
  'https://www.lordtracker.com/api/v1/alliance/lords/donations'

CSV body (send request context in query parameters):

memberId,total
member_id,2800

observedDate (or date) is required. Choose metricId or an exact metric name; a single metric defaults automatically. Weekly events require periodStart on their configured weekday and an observation within that period. Cumulative events have neither periodStart nor runId. Run events require a runId in that event. value/after/afterValue are aliases. before/beforeValue requires a comparison display; flags accept only 0 or 1. At most one MVP per run on its primary metric. Existing MVP replacement is included in undo. Omitted readings/MVP preserve existing fields; null sets unknown. Archived events reject writes.

curl -X POST -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: sheets-event-entries-2026-10-05' \
  --data '{"runId":"run_id","observedDate":"2026-10-05","entries":[{"memberId":"member_id","value":"8476000000","mvp":true}]}' \
  'https://www.lordtracker.com/api/v1/alliance/events/event_id/entries'

CSV body (send request context in query parameters):

memberId,metric,date,runId,after,mvp
member_id,Total Damage,2026-10-05,run_id,8476000000,true

Only Lords already on this battle's roster, after its start. Attendance is ATTENDED, NO_SHOW, EXCUSED or null (unknown); it is never inferred from score. Omitted score/attendance preserve existing fields. Explicit null sets unknown. Optional version rejects a battle changed since the caller read it. Roster assignments are never created.

curl -X POST -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: sheets-battlefield-points-2026-10-05' \
  --data '{"entries":[{"memberId":"member_id","score":"180000","attendance":"ATTENDED"}]}' \
  'https://www.lordtracker.com/api/v1/alliance/battles/battle_id/scores'

CSV body (send request context in query parameters):

memberId,score,attendance
member_id,180000,ATTENDED

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.lordtracker.com/api/v1/alliance?limit=100"

{
  "data": [
    {
      "id": "alliance_id",
      "name": "Alliance name",
      "tag": "TAG",
      "kingdom": 80
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.lordtracker.com/api/v1/alliance/lords?limit=100"

{
  "data": [
    {
      "id": "member_id",
      "name": "Lord name",
      "status": "ACTIVE",
      "gameLordId": null,
      "role": {
        "value": "R4",
        "observedAt": "2026-10-05T00:00:00.000Z",
        "source": "MANUAL"
      },
      "power": {
        "value": "126540800",
        "observedAt": "2026-10-05T00:00:00.000Z",
        "source": "MANUAL"
      },
      "kills": null,
      "heroPower": {
        "value": "48125300",
        "observedAt": "2026-10-05T00:00:00.000Z",
        "source": "MANUAL"
      },
      "castleLevel": {
        "value": "30",
        "observedAt": "2026-10-05T00:00:00.000Z",
        "source": "MANUAL"
      }
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.lordtracker.com/api/v1/alliance/lords/power?from=2026-10-01&to=2026-10-08&limit=100"

{
  "data": [
    {
      "memberId": "member_id",
      "name": "Lord name",
      "value": "126540800",
      "observedAt": "2026-10-05T00:00:00.000Z",
      "source": "MANUAL"
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.lordtracker.com/api/v1/alliance/lords/kills?from=2026-10-01&to=2026-10-08&limit=100"

{
  "data": [
    {
      "memberId": "member_id",
      "name": "Lord name",
      "value": "843251",
      "observedAt": "2026-10-05T00:00:00.000Z",
      "source": "MANUAL"
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.lordtracker.com/api/v1/alliance/lords/hero-power?from=2026-10-01&to=2026-10-08&limit=100"

{
  "data": [
    {
      "memberId": "member_id",
      "name": "Lord name",
      "value": "48125300",
      "observedAt": "2026-10-05T00:00:00.000Z",
      "source": "MANUAL"
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.lordtracker.com/api/v1/alliance/lords/vs?week=2026-10-05&limit=100"

{
  "data": [
    {
      "memberId": "member_id",
      "name": "Lord name",
      "weekStart": "2026-10-05T00:00:00.000Z",
      "resetHour": 0,
      "day": 1,
      "score": null,
      "recordedAt": null,
      "weeklyTotal": "25000000",
      "weeklyRecordedAt": "2026-10-05T00:00:00.000Z"
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.lordtracker.com/api/v1/alliance/lords/donations?week=2026-10-05&limit=100"

{
  "data": [
    {
      "memberId": "member_id",
      "name": "Lord name",
      "weekStart": "2026-10-05T00:00:00.000Z",
      "resetHour": 0,
      "total": null,
      "recordedAt": null
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.lordtracker.com/api/v1/alliance/performance?week=2026-10-05&limit=100"

{
  "data": [
    {
      "id": "member_id",
      "name": "Lord name",
      "weekStart": "2026-10-05T00:00:00.000Z",
      "standing": null,
      "score": null,
      "vsDaily": {
        "value": null,
        "recorded": 0,
        "expected": 6,
        "complete": false,
        "grade": "ungraded"
      },
      "vsWeekly": {
        "value": null,
        "recorded": 0,
        "expected": 1,
        "complete": false,
        "grade": "ungraded"
      },
      "donations": {
        "value": null,
        "recorded": 0,
        "expected": 1,
        "complete": false,
        "grade": "ungraded"
      }
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Workspace key required. Uses public kingdom observations.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.lordtracker.com/api/v1/kingdom?limit=100"

{
  "data": [
    {
      "kingdom": 80,
      "ranking": 4,
      "kind": "LORD",
      "observedAt": "2026-10-05T00:00:00.000Z",
      "limit": 100,
      "status": "PARTIAL",
      "captured": 75
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Workspace key required. Uses public kingdom observations.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.lordtracker.com/api/v1/kingdom/lords?ranking=4&limit=100"

{
  "data": [
    {
      "id": "public_entity_id",
      "name": "Lord name",
      "tag": "TAG",
      "value": "126540800",
      "position": 1,
      "observedAt": "2026-10-05T00:00:00.000Z"
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Workspace key required. Uses public kingdom observations.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.lordtracker.com/api/v1/kingdom/alliances?ranking=2&limit=100"

{
  "data": [
    {
      "id": "public_entity_id",
      "name": "Alliance name",
      "tag": "TAG",
      "value": "8436250000",
      "position": 1,
      "observedAt": "2026-10-05T00:00:00.000Z"
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Workspace key required. Uses public kingdom observations. lordId is the internal ID returned by /kingdom/lords. metric defaults to power; also supports kills, hero-power, heroHighestPower, level and pveMaxStage.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.lordtracker.com/api/v1/kingdom/lords/public_lord_id/history?from=2026-10-01&to=2026-10-08&limit=100"

{
  "data": [
    {
      "lordId": "public_lord_id",
      "name": "Lord name",
      "metric": "power",
      "value": "126540800",
      "observedAt": "2026-10-05T00:00:00.000Z",
      "source": "OFFICIAL_LEADERBOARD"
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}