Meme LemurDocs

Usage

Today's calls against your caps, the calls, tokens and cost of each day, space and key, and the usage alerts each member gets by email.

Read today's count against the cap #

GET /v1/usage

Returns how many generate calls your team has made today that count toward its daily cap, and how many are left. The day is the UTC calendar day, and the count resets at 00:00 UTC. The daily cap says which calls count.

Shell
curl https://api.memelemur.com/v1/usage \
  -H "Authorization: Bearer $MEMELEMUR_KEY" \
  -H "Memelemur-Space: design"
JSON
{
  "usage": {
    "day": "2026-10-02",
    "resetsAt": "2026-10-03T00:00:00.000Z",
    "team": { "used": 412, "cap": 1000, "remaining": 588 },
    "space": { "id": "design", "used": 37, "cap": 200, "remaining": 163 },
    "keys": [{ "keyId": "key_j15z8f8skojfdb1l", "used": 212, "cap": 500, "remaining": 288 }]
  },
  "credit": { "balanceMicros": 96450000, "atZero": "refused" }
}
Field What it is
day The UTC date the counts are for.
resetsAt When the counts go back to zero.
team Every counted call your team made today, in any space or none, against the team's cap.
space The counted calls made in the space of the Memelemur-Space header, against that space's cap. Null when the call has no header.
keys Each API key with a daily cap of its own, with its generate and match calls today. A key with no cap is left out.
credit.balanceMicros The prepaid credit your team has left, in millionths of a US dollar. It is the team's in every space.
credit.atZero What happens to your calls at a balance of zero. refused means generate, match and regenerate return 402 until credit is added, and billed means they keep working and are billed. The operator sets it. See when the credit runs out.

Read each day's usage #

GET /v1/usage/days

Returns what your team used on each UTC day in a range: how many calls it made, how many of them a model replied to, the tokens, and how long the calls took. A day with no stored call is left out.

Query What it does
from The first day, as YYYY-MM-DD. Left out, the range is the 30 days that end on to.
to The last day, as YYYY-MM-DD. Left out, it is today.
by space or key. Each day then has parts, its usage split by the space each call was made in or the key it was made with. Left out, or any other value, and a day has no parts.

One read covers at most 92 days. With the Memelemur-Space header it counts that space alone.

Shell
curl "https://api.memelemur.com/v1/usage/days?from=2026-10-01&to=2026-10-02" \
  -H "Authorization: Bearer $MEMELEMUR_KEY"
JSON
{
  "from": "2026-10-01",
  "to": "2026-10-02",
  "space": null,
  "days": [
    {
      "day": "2026-10-02",
      "calls": { "generate": 412, "match": 96, "render": 230, "total": 738 },
      "modelCalls": { "platform": 388, "team": 0, "total": 388, "usedFallback": 3 },
      "tokens": {
        "platform": { "inputTokens": 861360, "outputTokens": 74110, "cacheReadTokens": 0, "cacheWriteTokens": 0 },
        "team": { "inputTokens": 0, "outputTokens": 0, "cacheReadTokens": 0, "cacheWriteTokens": 0 }
      },
      "creations": {
        "standard": { "count": 495, "micros": 4900500 },
        "ownKey": { "count": 0, "micros": 0 },
        "animated": { "count": 13, "micros": 128700 },
        "total": { "count": 508, "micros": 5029200 }
      },
      "credit": { "coveredMicros": 3500000, "toBillMicros": 1529200 },
      "durations": {
        "elapsed": { "calls": 738, "sumMs": 1284120, "slowestMs": 9480 },
        "model": { "calls": 391, "sumMs": 903210 }
      }
    }
  ]
}
Field What it is
calls Every stored call of the day, by route.
modelCalls The calls a caption model replied to: how many the platform's key paid for, how many your own model key paid for, and how many the fallback model answered.
tokens The tokens the provider reported, kept apart for each key.
creations The calls you are charged for. A creation is a generate or match call that returned at least one meme. standard and ownKey are the two prices of a call that returned images, and ownKey applies while your team has its own model key stored. animated is a call that returned GIFs. It costs what the same call would have cost for images, unless your operator set a price for animated creations. count is how many, and micros is the amount in millionths of a US dollar, so 4900500 is $4.90. total.micros is what the day cost.
credit How much of creations.total.micros your prepaid credit covered, and toBillMicros, the rest, which is what you are billed for the day.
durations.elapsed The whole call. calls is how many calls have a duration, so sumMs / calls is the average, and slowestMs is the slowest call.
durations.model The wait for the caption model, with its retries. A call that asked no model has none.

With by, each day has parts. A part has every field of a day, with space (null for no space) or key in place of day, and the parts of a day add up to it. key is { "id", "type", "label", "revokedAt" }, where type is api or publishable, and it is null for the calls made signed in or by a chat app. An admin key's label is empty for a caller who cannot list admin keys. A part with no stored call that day is left out.

A render and a failed call are in calls and are free, so they are not in creations. The price is stored with each call, so a price that changes later changes later calls only.

Both routes add up the calls that were stored. A call a client sent twice is counted twice, and a call that failed before any model replied is not counted. A call that failed after a model replied, such as a prompt the model declined, is counted with its tokens.

Errors #

Status When
400 from or to is not a date, from is after to, or the range is longer than 92 days.

Read a range by space #

GET /v1/usage/spaces

Returns what your team used over a range of UTC days, added up for each space. from and to are the ones of GET /v1/usage/days, with the same defaults and the same limit of 92 days.

Shell
curl "https://api.memelemur.com/v1/usage/spaces?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $MEMELEMUR_KEY"
JSON
{
  "from": "2026-10-01",
  "to": "2026-10-31",
  "total": {
    "calls": { "generate": 412, "match": 96, "render": 230, "total": 738 },
    "modelCalls": { "platform": 388, "team": 0, "total": 388, "usedFallback": 3 },
    "tokens": {
      "platform": { "inputTokens": 861360, "outputTokens": 74110, "cacheReadTokens": 0, "cacheWriteTokens": 0 },
      "team": { "inputTokens": 0, "outputTokens": 0, "cacheReadTokens": 0, "cacheWriteTokens": 0 }
    },
    "creations": {
      "standard": { "count": 495, "micros": 4900500 },
      "ownKey": { "count": 0, "micros": 0 },
      "animated": { "count": 13, "micros": 128700 },
      "total": { "count": 508, "micros": 5029200 }
    },
    "credit": { "coveredMicros": 3500000, "toBillMicros": 1529200 },
    "durations": {
      "elapsed": { "calls": 738, "sumMs": 1284120, "slowestMs": 9480 },
      "model": { "calls": 391, "sumMs": 903210 }
    }
  },
  "spaces": [
    {
      "space": null,
      "calls": { "generate": 120, "match": 30, "render": 80, "total": 230 },
      "creations": { "total": { "count": 150, "micros": 1485000 } },
      "credit": { "coveredMicros": 1485000, "toBillMicros": 0 }
    },
    {
      "space": "design",
      "calls": { "generate": 292, "match": 66, "render": 150, "total": 508 },
      "creations": { "total": { "count": 358, "micros": 3544200 } },
      "credit": { "coveredMicros": 2015000, "toBillMicros": 1529200 }
    }
  ]
}

The rows above are cut short. Each row of spaces has every field of total, and they are the fields of a day of GET /v1/usage/days.

Field What it is
total Every stored call of your team in the range. It is the sum of the rows of spaces, so you do not need to add them up.
spaces One row for each space with a stored call in the range, in order of space. The row for the calls made in no space comes first.
space The id of the space. Null on the row for the calls made in no space.

A space with no stored call in the range has no row. A space you deleted keeps its row under its id, because a stored call keeps the id of the space it was made in.

The Memelemur-Space header changes nothing here. For one space day by day, send it to GET /v1/usage/days, and the days of that space add up to its row.

Errors #

Status When
400 from or to is not a date, from is after to, the range is longer than 92 days, or the query has a parameter other than from and to.

Read a range by key #

GET /v1/usage/keys

Returns what your team used over a range of UTC days, added up for each key the calls were made with: your API keys and the publishable keys of the meme picker and button. from and to are the ones of GET /v1/usage/days, with the same defaults and the same limit of 92 days.

Shell
curl "https://api.memelemur.com/v1/usage/keys?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $MEMELEMUR_KEY"
JSON
{
  "from": "2026-10-01",
  "to": "2026-10-31",
  "total": { "calls": { "generate": 412, "match": 96, "render": 230, "total": 738 } },
  "keys": [
    {
      "key": null,
      "calls": { "generate": 20, "match": 4, "render": 10, "total": 34 }
    },
    {
      "key": { "id": "key_j15z8f8skojfdb1l", "type": "api", "label": "billing service", "revokedAt": null },
      "calls": { "generate": 360, "match": 80, "render": 200, "total": 640 }
    },
    {
      "key": { "id": "pk_0c8m2qv7r4t1", "type": "publishable", "label": "site picker", "revokedAt": null },
      "calls": { "generate": 32, "match": 12, "render": 20, "total": 64 }
    }
  ]
}

The rows above are cut short. total and each row have every field of a day of GET /v1/usage/days, and total is the sum of the rows.

Field What it is
key The key the calls were made with. type is api or publishable. Null on the first row, which has the calls made signed in or by a chat app. An admin key's label is empty for a caller who cannot list admin keys.
keys One row for each key with a stored call in the range, in order of the key's id, after the row for no key. A revoked key keeps its row.

Calls stored before October 2026 have no key, so they are on the first row.

Errors #

Status When
400 from or to is not a date, from is after to, the range is longer than 92 days, or the query has a parameter other than from and to.

Usage alerts #

Each member of your team chooses which usage emails they get:

Alert When it is sent
nearCap A daily cap is nearly used: your team's, a space's own, an API key's or a publishable key's. "Nearly" is nearCapPercent of the cap, 80% unless the member chose another.
capReached One of those caps is used up, and calls it counts are refused until midnight UTC.
spike Your team made at least spikeMinCalls calls in the last hour, 50 unless the member chose another, and at least three times its average hourly rate over the week before. A team with no calls that week has an average of zero, so for it the minimum decides.
unsavedSpace Your calls are made in a space nobody has saved. The email lists each such space with how many calls and since when.

A cap alert goes to a member once per cap per UTC day, and a spike at most once in any six hours. An owner gets all four unless they turn them off, and an editor or a member gets none until they turn them on. A team with its own model key is not refused at its team or space cap, so it gets no alert about them.

The unsavedSpace email is sent once a space has been in use for 15 minutes, so the spaces of a new integration arrive in one email. Your team gets at most one a day, listing every unsaved space it has not been told about. A space is mentioned once, and again only if it is still in use and unsaved 30 days later. A space that was saved, or whose notice was dismissed, is not mentioned.

List the alerts #

GET /v1/alerts

Returns what each member gets, the alerts sent most recently, and the unsaved spaces your team's calls are made in. An owner and an admin key see every member. A signed-in editor or member sees only their own, and a regular key sees nobody. Every caller sees the unsaved spaces.

Query What it does
limit How many of the sent alerts to return, newest first, from 1 to 200. The default is 50.
Shell
curl https://api.memelemur.com/v1/alerts \
  -H "Authorization: Bearer $MEMELEMUR_ADMIN_KEY"
JSON
{
  "members": [
    { "email": "olive@acme.example", "role": "owner", "prefs": { "nearCap": true, "capReached": true, "spike": true, "unsavedSpace": true, "nearCapPercent": 80, "spikeMinCalls": 50 } },
    { "email": "mel@acme.example", "role": "member", "prefs": { "nearCap": false, "capReached": false, "spike": false, "unsavedSpace": false, "nearCapPercent": 80, "spikeMinCalls": 50 } }
  ],
  "sent": [
    { "email": "olive@acme.example", "kind": "nearCap", "subject": "key:key_j15z8f8skojfdb1l", "period": "2026-10-02", "used": 400, "cap": 500, "sentAt": "2026-10-02T15:05:00.412Z" },
    { "email": "olive@acme.example", "kind": "unsavedSpace", "subject": "team", "period": "2026-10-02", "used": 1, "cap": null, "sentAt": "2026-10-02T09:20:00.118Z" }
  ],
  "unsavedSpaces": [
    { "id": "support", "firstSeenAt": "2026-10-02T09:02:11.530Z", "lastSeenAt": "2026-10-02T15:02:40.007Z", "calls": 340, "notifiedAt": "2026-10-02T09:20:00.118Z" }
  ]
}

subject says what an alert was about: team, space:<id>, key:<id> for an API key or pk:<id> for a publishable key. period is the UTC day for a cap, or the UTC hour for a spike, such as 2026-10-02T15. For an unsavedSpace alert subject is team, period is the UTC day and used is how many spaces the email listed.

unsavedSpaces has each space that a call was made in during the last seven days, that nobody has saved, and whose notice nobody dismissed, the busiest first and at most 200. calls is a floor and not an exact count: at least that many calls were made in the space since firstSeenAt. notifiedAt is when an email last told your team about the space, or null.

Change a member's alerts #

PUT /v1/alerts/:email

Changes the alerts one member gets. A field left out keeps its value, and null puts it back to the default of the member's role. A signed-in person can change their own. An owner and an admin key can change anyone's.

Field Type What it does
nearCap boolean or null An email when a cap is nearly used.
capReached boolean or null An email when a cap is used up.
spike boolean or null An email when usage jumps.
unsavedSpace boolean or null An email when calls are made in a space nobody has saved.
nearCapPercent whole number from 1 to 99, or null How much of a cap is nearly used.
spikeMinCalls whole number from 10 to 1,000,000, or null The fewest calls in an hour that can count as a spike.
Shell
curl -X PUT https://api.memelemur.com/v1/alerts/mel@acme.example \
  -H "Authorization: Bearer $MEMELEMUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nearCap": true, "nearCapPercent": 90}'
JSON
{
  "member": {
    "email": "mel@acme.example",
    "role": "member",
    "prefs": { "nearCap": true, "capReached": false, "spike": false, "unsavedSpace": false, "nearCapPercent": 90, "spikeMinCalls": 50 },
    "saved": { "nearCap": true, "capReached": null, "spike": null, "unsavedSpace": null, "nearCapPercent": 90, "spikeMinCalls": null },
    "defaults": { "nearCap": false, "capReached": false, "spike": false, "unsavedSpace": false, "nearCapPercent": 80, "spikeMinCalls": 50 }
  }
}

prefs is what the member gets, saved is what they chose, and defaults is what their role gets for a field they did not choose.

Errors #

Status When
400 A field is not one of the six, or a value is out of range.
403 The caller is not an owner or an admin key, and the address is not their own.
404 Your team has no member with that address.

Dismiss the notice about an unsaved space #

POST /v1/alerts/unsaved-spaces/:id/dismiss

Stops the notices about one unsaved space: it leaves unsavedSpaces, and no email mentions it again. Use it for a space that is meant to run under your team's settings. The space's calls are not changed. An editor, an owner and any API key can call it, which is whoever can save a space. Returns the unsaved spaces that are left.

Shell
curl -X POST https://api.memelemur.com/v1/alerts/unsaved-spaces/support/dismiss \
  -H "Authorization: Bearer $MEMELEMUR_ADMIN_KEY"
JSON
{
  "unsavedSpaces": []
}

Errors #

Status When
400 The id is not a valid space id.
403 The caller is a signed-in member, who cannot save a space either.
404 No call of your team was made in that space while it was unsaved.