Skip to content
Docs

Your own Insights for a period

GET
/me/insights
curl --request GET \
  --url 'https://api.asklucy.eu/v1/me/insights?from=2026-04-15&to=2026-04-15' \
  --header 'Authorization: Bearer <token>'

Your own use of Lucy from from to to (UTC dates, both included, at most 366 days): how much and on which days, what you used Lucy with, what you haven’t tried yet, what it cost, your monthly allowance, your costliest conversations, and suggestions. Everything is yours alone.

amounts says whether euros are shown: always for org_admin, and for members unless the organization shows them shares of their allowance only (settings.member_costs shares). Without amounts, cost, allowance.limit, allowance.spent, costliest[].cost and suggestions[].effect are null; shares and percentages stay.

dismissed and muted are what you hid (dismissInsightSuggestion), so suggestions from Lucy Insights can be filtered the same way.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
from
required
string format: date
to
required
string format: date

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json
object
from
required
string format: date
to
required
string format: date
amounts
required

Whether euros are shown (org_admin, or members unless settings.member_costs is shares).

boolean
answers
required
integer
messages
required
integer
active_days
required

Days with at least one message.

integer
conversations
required

Conversations you wrote in (deleted ones too), without agent runs.

integer
agent_runs
required

Runs of the agents you own that ran or tried to (not a schedule’s skipped tick, not one still going).

integer
agents
required

How many of your agents ran.

integer
previous
required

The period of the same length just before from.

object
from
required
string format: date
to
required
string format: date
answers
required
integer
messages
required
integer
active_days
required
integer
conversations
required
integer
agent_runs
required
integer
days
required

One entry per day from from to to, oldest first.

Array<object>
object
day
required
string format: date
answers
required
integer
messages
required
integer
used
required
object
files
required

Files you uploaded.

integer
web_searches
required
integer
sandbox_seconds
required
integer
read_aloud
required

Parts of answers read aloud.

integer
desktop
required

You sent a message from the desktop app.

boolean
connectors
required

Connector apps Lucy used for you (its successful calls), most used first.

Array
object
service
required

The connector (Connector.id), e.g. m365.

string
service_name
required
string
app
required

The app (ConnectorApp.id), e.g. mail.

string
app_name
required
string
uses
required
integer
not_tried
required

What you may use now and haven’t in the 90 days up to to, in this order: web_search, connectors (none connected), calendar (a connected service’s calendar never used), agents (you own none), desktop (no computer registered), read_aloud.

Array<string>
Allowed values: web_search connectors calendar agents desktop read_aloud
cost
required
One of:

Spending by what it paid for. Everything of an agent run is in agents (its model calls, sandbox and searches alike); then the sandbox, web searches, Read aloud, and chats, the answers’ model calls and the summaries continued conversations start from. other is the rest: conversation titles, memory, search by meaning, and work for nobody in particular. total is the sum.

object
total
required
object
amount
required

Decimal amount, e.g. “12.50” (up to 6 decimals for small usage).

string
/^-?[0-9]+(\.[0-9]{1,6})?$/
currency
required
string
Allowed values: EUR
chats
required
object
amount
required

Decimal amount, e.g. “12.50” (up to 6 decimals for small usage).

string
/^-?[0-9]+(\.[0-9]{1,6})?$/
currency
required
string
Allowed values: EUR
agents
required
object
amount
required

Decimal amount, e.g. “12.50” (up to 6 decimals for small usage).

string
/^-?[0-9]+(\.[0-9]{1,6})?$/
currency
required
string
Allowed values: EUR
sandbox
required
object
amount
required

Decimal amount, e.g. “12.50” (up to 6 decimals for small usage).

string
/^-?[0-9]+(\.[0-9]{1,6})?$/
currency
required
string
Allowed values: EUR
web_search
required
object
amount
required

Decimal amount, e.g. “12.50” (up to 6 decimals for small usage).

string
/^-?[0-9]+(\.[0-9]{1,6})?$/
currency
required
string
Allowed values: EUR
read_aloud
required
object
amount
required

Decimal amount, e.g. “12.50” (up to 6 decimals for small usage).

string
/^-?[0-9]+(\.[0-9]{1,6})?$/
currency
required
string
Allowed values: EUR
activities

The organization’s report only. What Lucy Insights’ classifier cost the organization (zero for a group).

object
amount
required

Decimal amount, e.g. “12.50” (up to 6 decimals for small usage).

string
/^-?[0-9]+(\.[0-9]{1,6})?$/
currency
required
string
Allowed values: EUR
other
required
object
amount
required

Decimal amount, e.g. “12.50” (up to 6 decimals for small usage).

string
/^-?[0-9]+(\.[0-9]{1,6})?$/
currency
required
string
Allowed values: EUR
per_person

The organization’s report only. total over the people who used Lucy (used); zero when nobody did.

object
amount
required

Decimal amount, e.g. “12.50” (up to 6 decimals for small usage).

string
/^-?[0-9]+(\.[0-9]{1,6})?$/
currency
required
string
Allowed values: EUR
allowance
required
One of:

Your monthly allowance as Me.usage shows it: your own month limit, or the organization’s budget when that is closer to running out (limited_by organization). The organization’s amounts are shown to admins only.

object
window
required
string
Allowed values: month
percent_used
required
number
<= 100
limit
required
One of:
object
amount
required

Decimal amount, e.g. “12.50” (up to 6 decimals for small usage).

string
/^-?[0-9]+(\.[0-9]{1,6})?$/
currency
required
string
Allowed values: EUR
spent
required
One of:
object
amount
required

Decimal amount, e.g. “12.50” (up to 6 decimals for small usage).

string
/^-?[0-9]+(\.[0-9]{1,6})?$/
currency
required
string
Allowed values: EUR
resets_at
required
string | null format: date-time
limited_by
required
string
Allowed values: personal organization
costliest
required

Your three conversations that cost the most in the period (agent runs left out).

Array<object>
object
conversation
required
object
id
required
string
title
required
string
messages
required

All the conversation’s messages.

integer
cost
required
One of:
object
amount
required

Decimal amount, e.g. “12.50” (up to 6 decimals for small usage).

string
/^-?[0-9]+(\.[0-9]{1,6})?$/
currency
required
string
Allowed values: EUR
share
required

Of your spending in the period.

number
<= 1
sandbox_seconds
required
integer
web_searches
required
integer
suggestions
required
Array<object>

Something you could do differently. Lucy makes these kinds (Lucy Insights adds others, in the same shape):

  • auto_model: you chose a model for answers Auto would have given for less. model is yours, auto_model Auto’s most common pick, count the answers, effect what they would have cost less, and conversations up to 5 of yours still set to that model (maybe none), for “Switch these chats to Auto”.
  • fresh_chat: one long conversation (conversations, count its messages) is a big part of your spending: each answer re-reads it all. effect is what it cost in the period.
  • connect_files: you uploaded count files; you may connect connector so Lucy reads them where they are.
  • retries: you asked Lucy again for an answer count times (conversations: the latest ones).
  • ask_for_more: a limit stopped you count times, most often in window; you can ask your admins for more.
  • web_search: your organization lets Lucy search the web for you and you haven’t in 90 days.
  • personalization: you opened count chats of the last 90 days with the same instruction, text (as you last wrote it); said once in Personalization, Lucy follows it in every chat. Never one your own instructions already say.

Only suggestions with share of at least 0.1 come, at most 5, the biggest effect first.

object
key
required

Stable for the same advice; starts with the kind. Hide it with dismissInsightSuggestion.

string
<= 200 characters
kind
required
string
share
required

How much of your spending (or of your use, for kinds without an amount) this touches.

number
<= 1
effect
One of:
object
amount
required

Decimal amount, e.g. “12.50” (up to 6 decimals for small usage).

string
/^-?[0-9]+(\.[0-9]{1,6})?$/
currency
required
string
Allowed values: EUR
count
integer
model
object
id
required
string
label
required
string
auto_model
object
id
required
string
label
required
string
conversations
Array<object>
object
id
required
string
title
required
string
connector

One app of a connector, with the names people see.

object
service
required

The connector (Connector.id), e.g. m365.

string
service_name
required
string
app
required

The app (ConnectorApp.id), e.g. mail.

string
app_name
required
string
window
string
Allowed values: five_hours week month
text

personalization: the sentence, as you last wrote it. Your own words: only ever in your own Insights.

string
dismissed
required

Keys of the suggestions you hid.

Array<string>
muted
required

Kinds of suggestions you hid altogether.

Array<string>

Example 

{
  "used": {
    "connectors": [
      {
        "service_name": "Microsoft 365",
        "app_name": "Mail"
      }
    ]
  },
  "not_tried": [
    "web_search"
  ],
  "cost": {
    "total": {
      "amount": "50.00",
      "currency": "EUR"
    },
    "chats": {
      "amount": "50.00",
      "currency": "EUR"
    },
    "agents": {
      "amount": "50.00",
      "currency": "EUR"
    },
    "sandbox": {
      "amount": "50.00",
      "currency": "EUR"
    },
    "web_search": {
      "amount": "50.00",
      "currency": "EUR"
    },
    "read_aloud": {
      "amount": "50.00",
      "currency": "EUR"
    },
    "activities": {
      "amount": "50.00",
      "currency": "EUR"
    },
    "other": {
      "amount": "50.00",
      "currency": "EUR"
    },
    "per_person": {
      "amount": "50.00",
      "currency": "EUR"
    }
  },
  "allowance": {
    "window": "month",
    "limit": {
      "amount": "50.00",
      "currency": "EUR"
    },
    "spent": {
      "amount": "50.00",
      "currency": "EUR"
    },
    "limited_by": "personal"
  },
  "costliest": [
    {
      "cost": {
        "amount": "50.00",
        "currency": "EUR"
      }
    }
  ],
  "suggestions": [
    {
      "key": "auto_model:mistral-large-2512",
      "kind": "auto_model",
      "effect": {
        "amount": "50.00",
        "currency": "EUR"
      },
      "connector": {
        "service_name": "Microsoft 365",
        "app_name": "Mail"
      },
      "window": "five_hours",
      "text": "Answer in British English."
    }
  ]
}

400

Section titled “400”

The request is invalid; errors lists what’s wrong.

Media typeapplication/problem+json

RFC 9457 problem details.

object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
string
instance
string
request_id
string
quota

For quota-exceeded, the window that is used up.

object
window
required
string
Allowed values: five_hours week month
percent_used
required
number
<= 100
resets_at
required

Null for a rolling window that hasn’t started.

string | null format: date-time
limited_by
required

organization when the organization’s budget is closer to running out than the member’s own limit.

string
Allowed values: personal organization
request
One of:

A request as its member sees it, where they asked.

object
id
required
string
status
required
string
Allowed values: pending approved declined withdrawn
created_at
required
string format: date-time
decided_at
required
string | null format: date-time
note
required

What the admin who decided wrote back.

string | null
errors

Field-level problems (400 only).

Array<object>
object
field
required

JSON pointer into the request body.

string
message
required
string

Example 

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

Unique per request; quote it to support.

401

Section titled “401”

Missing, expired or invalid token.

Media typeapplication/problem+json

RFC 9457 problem details.

object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
string
instance
string
request_id
string
quota

For quota-exceeded, the window that is used up.

object
window
required
string
Allowed values: five_hours week month
percent_used
required
number
<= 100
resets_at
required

Null for a rolling window that hasn’t started.

string | null format: date-time
limited_by
required

organization when the organization’s budget is closer to running out than the member’s own limit.

string
Allowed values: personal organization
request
One of:

A request as its member sees it, where they asked.

object
id
required
string
status
required
string
Allowed values: pending approved declined withdrawn
created_at
required
string format: date-time
decided_at
required
string | null format: date-time
note
required

What the admin who decided wrote back.

string | null
errors

Field-level problems (400 only).

Array<object>
object
field
required

JSON pointer into the request body.

string
message
required
string

Example 

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

Unique per request; quote it to support.

GET/me/insights
curl "https://api.asklucy.eu/v1/me/insights" \
  -H "Authorization: Bearer $LUCY_TOKEN"

Try it

Nothing is sent without a token.