Skip to content
Docs

The organization's Insights

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

Adoption, use, cost and where to act, from from to to (UTC dates, both included, at most 366 days), for the organization or one group of the identity provider (group).

People are the organization’s active members who are persons (kind person), of the group when one is given. Use (answers, messages, weeks, features) counts them only. Cost is the whole ledger of the organization (its service agents and Lucy’s own work for it included), or for a group its people’s. month is always the organization’s current calendar month.

Nothing here says what anyone worked on: no conversations, no content. What people did by activity or client is Lucy Insights’ (openapi/lucy-insights.yaml), with cells of fewer than settings.insights_min_group people folded.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
from
required
string format: date
to
required
string format: date
group
string
<= 200 characters

A group’s ID (GET /org/groups); 404 for a group the organization doesn’t have.

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json
object
from
required
string format: date
to
required
string format: date
group
required
One of:
object
id
required
string
name
required
string
source
required

Where the group and its members come from.

string
Allowed values: identity_provider
member_count
integer | null
people
required

Members in scope.

integer
used
required

Of them, people who sent a message in the period.

integer
previous_used
required

The same in the period of the same length just before.

integer
new
required

People whose first message ever was in the period.

integer
not_started
required

People who never sent a message, longest-standing account first (at most 50).

Array<object>
object
user
required
object
id
required

Zitadel user ID.

string
name
required
string
email
string | null format: email
kind

service is a customer system’s Zitadel service user; agent is a service agent (its ID is the agt_ ID), the author of its runs’ messages.

string
Allowed values: person service agent
since
required

When their account was made; null when unknown.

string | null format: date
answers
required
integer
messages
required
integer
satisfaction
required

How the people in scope rated the period’s answers: the share of their ratings (thumbs up or down) that are positive, three decimals. Null unless there are at least 30 ratings from at least 5 people: it is never one person’s. Feedback reasons and comments are never read here.

number | null
<= 1
ratings
required

The ratings satisfaction counts, given by the people in scope to the period’s answers.

integer
weekly
required

The 12 weeks (Monday to Sunday, UTC) up to the one with to, oldest first; the last stops at to.

Array<object>
object
week
required

Its Monday.

string format: date
people
required

People with a message that week.

integer
by_group
required

The whole organization only (empty for a group): each group of the identity provider, and a row with group null for members in no group; the costliest first. Someone in several groups counts in each.

Array<object>
object
group
required
One of:
object
id
required
string
name
required
string
source
required

Where the group and its members come from.

string
Allowed values: identity_provider
member_count
integer | null
people
required
integer
used
required
integer
answers
required
integer
cost
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
satisfaction
required

As the report’s satisfaction, for the group’s people, with the same rule (30 ratings, 5 people).

number | null
<= 1
ratings
required
integer
features
required

How many people in scope used each in the period.

object
connectors
required
integer
web_search
required
integer
agents
required

People whose own agents ran.

integer
agent_runs
required

Runs of their agents (and of service agents, for the whole organization).

integer
desktop
required

People who sent a message from the desktop app.

integer
read_aloud
required
integer
sandbox
required
integer
agents
required

Agents that ran in the period (people in scope’s own, and for the whole organization its service agents), costliest first, at most 10. A schedule’s skipped ticks don’t count as runs.

Array<object>
object
agent
required
object
id
required
string
name
required
string
runs
required
integer
failed
required
integer
cost
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
last_error
required

The latest failed run’s error message, shortened.

string | null
last_failed_at
required
string | null format: date-time
cost
required

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
by_model
required

The answers’ model calls by the model that answered, costliest first.

Array<object>
object
model
required
object
id
required
string
label
required
string
answers
required
integer
cost
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
days
required

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

Array<object>
object
day
required
string format: date
cost
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
answers
required
integer
month
required

The organization’s current calendar month (UTC), whatever the period or group: spent so far, the budget that applies (the lower of the admins’ and the contract’s, as GET /org/quotas), and the month’s end at the pace so far.

object
spent
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
budget
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
forecast
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
resets_at
required
string format: date-time
actions
required
Array<object>
<= 6 items

Something an admin could do, at most one of each kind, the biggest effect first:

  • model_fit: answers by a chosen model or the organization’s default that Auto would have given for less, for the model where that saves the most: count answers, people, auto_model (Auto’s most common pick), effect per month (the period’s saving scaled to 30 days).
  • not_started: people who never sent a message, with an account older than a week.
  • agent_failing: the agent whose runs failed most in the last 7 days (count, at least 2), with its last_error.
  • limits_reached: the group (null: people in no group) whose people a limit refused most in the period: count, people, and the window refused most.
  • budget_forecast: at this pace the month ends over its budget by effect.
  • requests_waiting: requests that have waited more than two days for a decision.
object
kind
required
string
Allowed values: model_fit not_started agent_failing limits_reached budget_forecast requests_waiting
effect
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
count
integer
people
integer
model
object
id
required
string
label
required
string
auto_model
object
id
required
string
label
required
string
agent
object
id
required
string
name
required
string
group
One of:
object
id
required
string
name
required
string
source
required

Where the group and its members come from.

string
Allowed values: identity_provider
member_count
integer | null
window
string
Allowed values: five_hours week month
last_error
string
requests
integer

Example 

{
  "group": {
    "source": "identity_provider"
  },
  "not_started": [
    {
      "user": {
        "kind": "person"
      }
    }
  ],
  "satisfaction": 0.874,
  "by_group": [
    {
      "group": {
        "source": "identity_provider"
      },
      "cost": {
        "amount": "50.00",
        "currency": "EUR"
      }
    }
  ],
  "agents": [
    {
      "cost": {
        "amount": "50.00",
        "currency": "EUR"
      }
    }
  ],
  "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"
    }
  },
  "by_model": [
    {
      "cost": {
        "amount": "50.00",
        "currency": "EUR"
      }
    }
  ],
  "days": [
    {
      "cost": {
        "amount": "50.00",
        "currency": "EUR"
      }
    }
  ],
  "month": {
    "spent": {
      "amount": "50.00",
      "currency": "EUR"
    },
    "budget": {
      "amount": "50.00",
      "currency": "EUR"
    },
    "forecast": {
      "amount": "50.00",
      "currency": "EUR"
    }
  },
  "actions": [
    {
      "kind": "model_fit",
      "effect": {
        "amount": "50.00",
        "currency": "EUR"
      },
      "group": {
        "source": "identity_provider"
      },
      "window": "five_hours"
    }
  ]
}

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.

403

Section titled “403”

The token is valid but lacks the role this needs.

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.

404

Section titled “404”

No such object in your organization.

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/org/insights
curl "https://api.asklucy.eu/v1/org/insights" \
  -H "Authorization: Bearer $LUCY_TOKEN"

Try it

Nothing is sent without a token.