Lanyard (Discord Presence) API

Free Discord presence API with no key: online status, activities, Spotify track and a per-user key-value store, over REST or WebSocket. Tested example included.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the Lanyard (Discord Presence) API?

Lanyard exposes a Discord user's live presence — status, current activities, and Spotify playback — as plain REST JSON with no API key. It only works for users who have joined the Lanyard Discord server, which is how they opt in.

Discord has no public way to read someone's presence without running a bot, which is why so many personal sites gave up on the "here is what I'm listening to right now" widget. Lanyard solves it by running that bot once, centrally: join their Discord server and your presence becomes readable at a plain URL that anyone can fetch from browser JavaScript.

Two things make it more than a novelty. First, there is a WebSocket alongside the REST endpoint, so a widget can update the moment your status changes rather than polling. Second, every monitored user gets a small key-value store — the `kv` object — which Lanyard serves back verbatim; people use it for social links, a status note, or whatever their site needs. Since the KV content is arbitrary user data of arbitrary size, treat it as untrusted and do not assume it is small.

Quick facts

Base URL: https://api.lanyard.rest/v1
Authentication: No API key to read presence. Writing to your own KV store needs a token issued by the Lanyard bot; reads are open.
Rate limit: No published limit on reads. Use the WebSocket rather than tight polling if you need live updates.
Pricing: Free. Lanyard is open source and can be self-hosted if you would rather not depend on the public instance.
CORS: Enabled — callable directly from browser JavaScript
Official docs: Read the docs

How to use the Lanyard (Discord Presence) API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Read a monitored user's Discord presence

GET https://api.lanyard.rest/v1/users/156114103033790464

curl

curl 'https://api.lanyard.rest/v1/users/156114103033790464'

JavaScript (fetch)

const res = await fetch("https://api.lanyard.rest/v1/users/156114103033790464");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://api.lanyard.rest/v1/users/156114103033790464", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200 (truncated)

{
  "data": {
    "kv": {
      "discord": "https://dstn.to/discord",
      "github": "https://github.com/dustinrouillard",
      "ip": "::1",
      "lanyard": "wtf",
      "note": "I make things, or something like that",
      "riderr": "https://riderr.app",
      "twitter": "https://twitter.com/dustinrouillard",
      "website": "https://dstn.to"
    },
    "discord_user": {
      "avatar": "23d093e9b8bc09e0341e1ce18b217602",
      "avatar_decoration_data": {
        "asset": "a_e3ec2d8cccdcb68819b2910c0787d3a4",
        "expires_at": null,
        "sku_id": "1531403489727746310"
      },
      "bot": false,
      "collectibles": {
        "nameplate": {
          "asset": "nameplates/spectrum_array/1531411317477478654/",
          "expires_at": null,
          "label": "Red and orange light waves ripple and sparkle",
          "palette": "bubble_gum",
          "sku_id": "1531411317477478654"
        }
      },
      "discriminator": "0",
      "display_name": "Dustin",
      "display_name_styles": {
        "colors": [
          1874155
        ],
        "effect_id": 5,
        "font_id": 8
      },
      "global_name": "Dustin",
      "id": "156114103033790464",
      "primary_guild": null,
      "public_flags": 131648,
      "username": "dstn.to"
    },
    "activities": [
      {
        "content_classification": {
          "data": null,
          "loaded": true
        },
        "created_at": 1787298783475,
        "emoji": {
          "name": "📸"
        },
        "id": "custom",
        "name": "Custom Status",
        "session_id": "ab5f6bab10da05f7eb780af56c

Parameters

Parameter	Type	Required	Description
`(user id)`	path	Required	Discord snowflake id of a user who has joined the Lanyard Discord server. `156114103033790464`

Response fields

data.discord_userobject: Username, global name, avatar hash and public flags. Build the avatar URL from `id` and `avatar`.
data.discord_statusstring: `online`, `idle`, `dnd` or `offline`.
data.activitiesarray: Current activities. Type 4 is the custom status; type 2 is listening. Playing a game shows up here with its name and timestamps.
data.listening_to_spotifyboolean: Convenience flag, mirrored by a richer `spotify` object with track, artist, album art and start/end timestamps.
data.active_on_discord_web / _desktop / _mobileboolean: Which clients the user is connected from.
data.kvobject: Arbitrary user-controlled key-value pairs. Values can be long — one documented user stores a full synced-lyrics blob here.
success / errorboolean / object: An unmonitored user id returns `success: false` with `error.code` set to `user_not_monitored`.

What you can build with the Lanyard (Discord Presence) API

Show a live "currently listening on Spotify" card on a personal site
Display an online/offline dot next to a profile
Drive a status widget from the WebSocket instead of polling
Read your own KV store to publish social links from one place

Common errors and how to fix them

`user_not_monitored`

That Discord user has not joined the Lanyard Discord server.

Fix: Presence is opt-in and there is no way around it. Only monitored users return data.

Everything null while the user is clearly online

Discord only broadcasts presence when the user allows it, and invisible mode reports as offline.

Fix: Treat `offline` as "not visible", not as "definitely not there".

Huge response

The `kv` store holds arbitrary user content.

Fix: Do not assume a small payload. Cap what you read and render, and never inject KV values into a page unescaped.

Stale data when polling

REST returns a snapshot.

Fix: Use the WebSocket gateway for anything that should feel live; polling every few seconds is both slower and ruder.

Lanyard (Discord Presence) API — frequently asked questions

Do I need an API key for Lanyard?

No. Reading presence needs nothing at all. Writing to your own key-value store requires a token you get from the Lanyard bot, but that is a separate concern.

Why does my Discord id return user_not_monitored?

Lanyard can only see users who have joined its Discord server — that membership is the opt-in. Join the server and your id starts returning data within moments.

Can I get live updates instead of polling?

Yes. Lanyard runs a WebSocket gateway that pushes presence changes as they happen, which is the intended way to drive a live widget.

Is it safe to render the kv values directly?

No. They are arbitrary strings set by the user, so escape them like any other untrusted input and be prepared for values much larger than you expect.

Tools that pair with this API

Discord Timestamp Generator

Turn any date and time into Discord timestamp tags that show in each reader's own timezone — all seven formats previewed live with copy buttons.

Discord Embed Generator

Build Discord webhook embed JSON with a live preview: title, colour, author, fields, images, footer and timestamp, with every character limit checked.

Discord Text Formatter

Build Discord markdown — bold, italic, underline, spoilers, quotes — plus colored text with ANSI code blocks. Live preview and copy-ready output.

Lanyard (Discord Presence) is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.