> For the complete documentation index, see [llms.txt](https://docs.flowretail.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowretail.com/docs/developers/api-documentation/service/get-service-order-statistics.md).

# Get service order statistics

Get the numbers behind the service manager dashboard: how the open service orders are spread across the states, how much open work each user is carrying, how long service orders take to get through and where the time goes, how often the promised date is missed, which weekdays the work comes in on, how the job types compare, and which open service orders have been waiting longest. Every figure is computed from the service orders' event history, so the numbers say the same thing the timelines do. avgWorkOpenDays also reads the stores' openDays and serviceCountWeekendsAsWorkingDays and the holiday calendar as they stand at the request. The period given by fromDate and toDate applies to the period figures: completedCount, avgTurnaroundDays, avgActiveTurnaroundDays, avgQueueDays, avgWorkDays, avgWorkOpenDays, avgPickupDays, overdueRate and serviceJobTypes all read the service orders completed within the period, and registeredCount and registrationsByWeekday read the ones registered within it. Completed means reached COMPLETE — a cancelled service order takes no part in the period figures, and a reopened one counts in the period of its latest completion. openByState, workload and oldestOpen are not scoped by it: they always describe the service orders that are open right now. Asking without a period still returns those three in full. The period is not capped. Every figure is computed live from the event history on each request, over whatever period is asked for, so a year is asked for exactly the way a week is. storeUids narrows everything, the open figures as well as the period figures, to the stores that own the service orders — the stores the work sits with and where the customers collect. That is the owning store, not the store a service order was taken in at; the two differ whenever a service order has been moved between stores. Left out, every store the caller holds SERVICE\_ORDER or REPORTING at is counted. This endpoint answers for the caller's stores as a whole, or for the stores named in storeUids taken together. Compare the stores against each other, for a store comparison or a top or bottom list, through the per-store service order statistics endpoint. The dashboard's tiles and saved-list cards are not read from here. Those come from the service order counts endpoint, which counts whatever filters each of them stands for. The figures key on the store that owns a service order, never on the store it was taken in at: a case that has moved counts for the store it moved to, and for no other. Being able to read a case from another store, the store it was taken in at included, does not make it that store's work here. The figures count only the service orders owned by the stores the caller holds SERVICE\_ORDER or REPORTING at — every store of the tenant for a tenant-wide holder, the organization's stores for an organization holder, the assigned stores for a store-level holder, the two permissions adding up — because a figure is a store's work, not a case to find; the tenant-level service order search reaches further, to every service order of the tenant, for a caller holding SERVICE\_ORDER. A caller holding REPORTING and not SERVICE\_ORDER is answered every figure, workload and oldestOpen included, exactly as a caller holding SERVICE\_ORDER at the same stores is. A caller holding neither, a user with no role assignments included, is refused with a 403. Opening a service order oldestOpen names through get-serviceorders-by-id asks for SERVICE\_ORDER, so a caller holding REPORTING alone sees the entry and is refused on opening it.

Required permissions: SERVICE\_ORDER,REPORTING

```json
{"openapi":"3.0.2","info":{"title":"Flow Retail API version 2","version":"2.0.0"},"tags":[{"name":"Service","description":"Service"}],"servers":[{"description":"Flow Retail Production","url":"https://api.flowretail.com/v2"},{"description":"Flow Retail Stage","url":"https://api.stage.flowretail.com/v2"}],"security":[{"accessToken":[]},{"authToken":[]},{"integrationToken":[]}],"components":{"securitySchemes":{"accessToken":{"description":"Access token recevied after user login with a deviceToken","scheme":"bearer","type":"http"},"authToken":{"description":"Token received from the auth service","scheme":"bearer","type":"http"},"integrationToken":{"scheme":"bearer","type":"http"}},"responses":{"ServiceOrderStatsResponse":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceOrderStatsResponseSchema"}}}}},"schemas":{"ServiceOrderStatsResponseSchema":{"title":"ServiceOrderStatsResponseSchema","description":"The numbers behind the service manager dashboard. Every figure is computed from the service orders' event history, so what is returned is the same record the timeline shows rather than a separate tally that can drift away from it. Time on a status is classified by the state that status maps to now: remapping a status to another state reclassifies the time spent on it, past and future alike, so the figures follow the tenant's current reading of its workflow. avgWorkOpenDays likewise reads the stores' openDays and serviceCountWeekendsAsWorkingDays and the holiday calendar as they stand at the request, so changing them recomputes past periods too.\nTwo different questions are answered in one response, and they are not scoped the same way. openByState, workload and oldestOpen describe how things stand right now — they always reflect the service orders that are open at the moment of the call, whatever period was asked for. A service order is open here in the same sense the service order search's open filter means it. Everything else is a period figure. completedCount, avgTurnaroundDays, avgActiveTurnaroundDays, avgQueueDays, avgWorkDays, avgWorkOpenDays, avgPickupDays, overdueRate and serviceJobTypes are all computed over the service orders that were completed within the period; registeredCount and registrationsByWeekday read the ones registered within it instead. A call with no period therefore still returns the three open figures in full.\nCompleted means reached COMPLETE: a cancelled service order is finished, never completed, and takes no part in the period figures. A service order that was reopened counts in the period of its latest transition into COMPLETE, and not at all while it is open again.\nEach average and overdueRate is taken over its own service orders — avgQueueDays over the ones that entered IN_PROGRESS, avgPickupDays over the ones that entered READY_FOR_PICKUP — and is null when there are none of them, never 0. 0 is a real figure: work started the moment the case was registered, or no case was late. null says no service order went through what the figure measures, so there is nothing to show and nothing to rank.\nThe period is not capped. Every figure is computed live from the event history on each request, over whatever period is asked for.\nstoreUids narrows everything, both the open figures and the period figures, to the stores that own the service orders.\nThe tiles and the saved-list cards on the dashboard are not read from here — those come from the service order counts endpoint, which answers whatever filters they stand for. This endpoint is the rest of the dashboard.","type":"object","required":["openByState","workload","avgActiveTurnaroundDays","avgTurnaroundDays","oldestOpen","avgQueueDays","avgWorkDays","avgWorkOpenDays","avgPickupDays","overdueRate","registeredCount","completedCount","registrationsByWeekday","serviceJobTypes"],"properties":{"openByState":{"type":"array","description":"How the open service orders are spread across the states right now, one entry per state. Not scoped by the period.","items":{"$ref":"#/components/schemas/ServiceOrderStatsStateCountSchema"}},"workload":{"type":"array","description":"How much open work each user is carrying right now, one entry per user who has something assigned to them. Not scoped by the period.","items":{"$ref":"#/components/schemas/ServiceOrderStatsWorkloadSchema"}},"registeredCount":{"type":"integer","description":"The number of service orders registered within the period, whatever has become of them since. This is the population registrationsByWeekday spreads across the week."},"completedCount":{"type":"integer","description":"The number of service orders completed within the period. avgTurnaroundDays and avgActiveTurnaroundDays are computed over all of them, avgQueueDays and avgWorkDays over the ones among them that entered IN_PROGRESS, avgWorkOpenDays over the ones among them that entered IN_PROGRESS and whose store has openDays, avgPickupDays over the ones that entered READY_FOR_PICKUP and overdueRate over the ones carrying a readyAtEstimate."},"avgTurnaroundDays":{"type":"number","nullable":true,"description":"The average number of days from registration to completion, over the service orders that were completed within the period. A service order that is still open is never part of it, however long it has been waiting.\nnull when no service order was completed in the period."},"avgActiveTurnaroundDays":{"type":"number","nullable":true,"description":"The same average, counting only the time the service orders spent in the states where the store or workshop holds the responsibility: NOT_STARTED, IN_TRANSIT and IN_PROGRESS. Time spent in AWAITING_PRODUCT, WAITING_CUSTOMER, WAITING_SUPPLIER or READY_FOR_PICKUP does not count: a customer who takes a week to answer does not make the workshop look slow. Which states count is owned by the platform and follows the state, never the status name.\nComputed over the same service orders as avgTurnaroundDays, from the timestamps in the event history. null when no service order was completed in the period."},"avgQueueDays":{"type":"number","nullable":true,"description":"The average number of days from registration to the first time work started — the first transition into the state IN_PROGRESS — over the service orders that were completed within the period. It is how long a service order lies untouched before anyone picks it up, told apart from how long the work itself takes.\nService orders that never entered IN_PROGRESS take no part in this average: a case completed without work ever starting has no queue to measure. null when none of the completed service orders entered the state."},"avgWorkDays":{"type":"number","nullable":true,"description":"The average number of days from the first time work started — the first transition into the state IN_PROGRESS — to completion, over the service orders that were completed within the period. Together with avgQueueDays it splits the turnaround into the waiting and the working.\nService orders that never entered IN_PROGRESS take no part in this average, exactly as for avgQueueDays. null when none of the completed service orders entered the state."},"avgWorkOpenDays":{"type":"number","nullable":true,"description":"avgWorkDays counted only inside the opening hours of the store that owns the service order, on the store's working days (serviceCountWeekendsAsWorkingDays), in the tenant's timezone: a full working day counts 1, and part of one its share of that day's open hours. Like avgWorkDays, it is taken over the service orders that were completed within the period and entered IN_PROGRESS. Service orders whose store has no openDays are left out; null when none is left."},"avgPickupDays":{"type":"number","nullable":true,"description":"The average number of days from the first transition into the state READY_FOR_PICKUP to completion, over the service orders that were completed within the period — how long finished work waits on the shelf to be collected. It is the queue at the counter rather than the queue at the bench.\nService orders that never entered READY_FOR_PICKUP take no part in this average: a case handed straight back over the counter says nothing about how long a shelf is waited on. null when none of the completed service orders entered the state."},"overdueRate":{"type":"number","nullable":true,"description":"The share of the service orders completed within the period whose work was ready after their readyAtEstimate, from 0 to 1. 0.25 means a quarter of them were late.\nThe work is ready from the start of the unbroken stretch on statuses of the states READY_FOR_PICKUP, COMPLETE and CANCELLED that runs up to the service order's latest completion — the latest moment it came off a status of any other state, not the first entry into READY_FOR_PICKUP that avgPickupDays measures from — or at that completion when no such stretch precedes it. It is the overdue search filter's reading of lateness applied to the service order's history, with the readyAtEstimate as it stands and the statuses' states as they map now: one ready by its readyAtEstimate is on time however late the customer collects it, also when a hand-over is reopened onto READY_FOR_PICKUP, and one taken back to work after its readyAtEstimate is late.\nA service order carrying no readyAtEstimate takes no part in the share, on either side of it. null when none of the completed service orders carried one."},"registrationsByWeekday":{"type":"array","description":"How the registrations of the period are spread across the days of the week, one entry per weekday — what says which day the counter fills up on and where the staffing has to be.\nLike registeredCount, it reads the service orders registered within the period rather than the ones completed within it. All seven weekdays are always returned, the ones nothing was registered on as zeros.","items":{"$ref":"#/components/schemas/ServiceOrderStatsWeekdayCountSchema"}},"serviceJobTypes":{"type":"array","description":"How the work went per job type, one entry per job type that appears on the service orders completed within the period. It is what says that a screen replacement goes out the door in two days and a motherboard repair in nine.\nA service order carrying several job types counts toward each of them, so the entries' completed counts add up to more than the number of service orders completed. A job type nothing was completed under is not returned.","items":{"$ref":"#/components/schemas/ServiceOrderStatsServiceJobTypeSchema"}},"oldestOpen":{"type":"array","description":"The open service orders that have been waiting longest, oldest first — the one registered furthest back comes first. Ordering is by registration date ascending, never newest first.\nA short list of fixed length for the dashboard panel, not a paged list and not every old service order. Page through the whole set with the service order search endpoint sorted by creation date instead. Not scoped by the period.","items":{"$ref":"#/components/schemas/ServiceOrderStatsOldestOpenSchema"}}}},"ServiceOrderStatsStateCountSchema":{"title":"ServiceOrderStatsStateCountSchema","description":"How many open service orders are on one state right now. Every state is returned, including the ones nothing is on, so the panel keeps its shape from one reading to the next.","type":"object","required":["state","count"],"properties":{"state":{"description":"The state the service orders counted here are on.","allOf":[{"$ref":"#/components/schemas/ServiceStateENUM"}]},"count":{"type":"integer","description":"The number of open service orders on this state."}}},"ServiceStateENUM":{"title":"ServiceStateENUM","description":"Where a service order stands, as the platform understands it. Every status a tenant defines maps to exactly one state, and it is the state Flow reasons about: the workspace filters, the wording the portal shows the customer and the turnaround figures all follow the state rather than the name the status was given.\nAWAITING_PRODUCT: the service order is registered, but the device has not arrived yet.\nNOT_STARTED: the device is here and the work is queued.\nIN_TRANSIT: the service order is in a box on its way between locations.\nIN_PROGRESS: the work is being done.\nWAITING_CUSTOMER: waiting for an answer from the customer — never for the device, which is what AWAITING_PRODUCT is for.\nWAITING_SUPPLIER: waiting for parts or for an answer from a supplier.\nREADY_FOR_PICKUP: the outcome is ready to be handed over.\nCOMPLETE: the customer has the device back. This is the handover, never the payment.\nCANCELLED: the service order ended without a completed repair.\nCOMPLETE and CANCELLED are the terminal states.\nThe states are owned by the platform: tenants never define or rename them, and only decide which state each of their own statuses maps to. A status that exists today keeps the state it has until the tenant remaps it — nothing is remapped for them.\nExtensible — new states may be added, so clients must not fail on a value they do not know.","type":"string","enum":["AWAITING_PRODUCT","NOT_STARTED","IN_TRANSIT","IN_PROGRESS","WAITING_CUSTOMER","WAITING_SUPPLIER","READY_FOR_PICKUP","COMPLETE","CANCELLED"]},"ServiceOrderStatsWorkloadSchema":{"title":"ServiceOrderStatsWorkloadSchema","description":"How much open work one user is carrying right now. Only users who have at least one open service order assigned to them are returned — a user with nothing on their plate is not listed.\nService orders nobody has picked up are not counted here, because they belong to a store rather than to a person. Read those from the service order search endpoint, with an empty string as the one entry in assignedUserUids.","type":"object","required":["tenantUserUid","tenantUserDisplayName","openCount"],"properties":{"tenantUserUid":{"$ref":"#/components/schemas/UID"},"tenantUserDisplayName":{"type":"string","description":"The user's name as it reads now. Included so the workload panel can be shown without looking every user up."},"openCount":{"type":"integer","description":"The number of open service orders assigned to this user."}}},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"ServiceOrderStatsWeekdayCountSchema":{"title":"ServiceOrderStatsWeekdayCountSchema","description":"How many service orders were registered on one weekday within the period. All seven weekdays are returned, including the ones nothing was registered on, so the panel keeps its shape from one reading to the next.","type":"object","required":["weekday","count"],"properties":{"weekday":{"description":"The weekday the service orders counted here were registered on.","allOf":[{"$ref":"#/components/schemas/WeekDayENUM"}]},"count":{"type":"integer","description":"The number of service orders registered on this weekday within the period."}}},"WeekDayENUM":{"enum":["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY","SUNDAY"],"title":"WeekDayENUM","type":"string"},"ServiceOrderStatsServiceJobTypeSchema":{"title":"ServiceOrderStatsServiceJobTypeSchema","description":"How the work of one job type went over the period, computed over the service orders completed within the period that carry this job type. A service order carrying several job types counts toward each of them, so these completed counts add up to more than the number of service orders completed.\nOne entry per job type that appears on the period's completed service orders. A job type nothing was completed under is not listed.","type":"object","required":["serviceJobTypeUid","serviceJobTypeName","completedCount","avgQueueDays","avgWorkDays","avgWorkOpenDays","avgPickupDays"],"properties":{"serviceJobTypeUid":{"$ref":"#/components/schemas/UID"},"serviceJobTypeName":{"type":"string","description":"The job type's name as it reads now. Included so the breakdown can be shown without looking every job type up."},"completedCount":{"type":"integer","description":"The number of service orders carrying this job type that were completed within the period. avgQueueDays and avgWorkDays are computed over the ones among them that entered IN_PROGRESS, avgWorkOpenDays over the ones among them that entered IN_PROGRESS and whose store has openDays and avgPickupDays over the ones that entered READY_FOR_PICKUP, exactly as on the statistics response."},"avgQueueDays":{"type":"number","nullable":true,"description":"The average number of days from registration to the first time work started, over these service orders that entered IN_PROGRESS. It means exactly what avgQueueDays means on the statistics response. null when none of them did."},"avgWorkDays":{"type":"number","nullable":true,"description":"The average number of days from the first time work started to completion, over these service orders that entered IN_PROGRESS. It means exactly what avgWorkDays means on the statistics response. null when none of them did."},"avgWorkOpenDays":{"type":"number","nullable":true,"description":"avgWorkDays counted only inside the opening hours of the store that owns the service order, on the store's working days (serviceCountWeekendsAsWorkingDays), in the tenant's timezone: a full working day counts 1, and part of one its share of that day's open hours. Like avgWorkDays, it is taken over these service orders that entered IN_PROGRESS. Service orders whose store has no openDays are left out; null when none is left."},"avgPickupDays":{"type":"number","nullable":true,"description":"The average number of days finished work waited to be collected, over these service orders. It means exactly what avgPickupDays means on the statistics response: the ones that never entered READY_FOR_PICKUP are left out, and it is null when none of them did."}}},"ServiceOrderStatsOldestOpenSchema":{"title":"ServiceOrderStatsOldestOpenSchema","description":"An open service order that has been waiting a long time, slimmed down to what is needed to show it in the dashboard panel and open it. Read the whole service order through get-serviceorders-by-id, which asks for SERVICE_ORDER.","type":"object","required":["serviceOrderUid","storeUid","serviceNumber","title","createdAt"],"properties":{"serviceOrderUid":{"$ref":"#/components/schemas/UID"},"storeUid":{"description":"The store that owns the service order now — the store the figures key on, never the store it was taken in at. A service order that has been moved to another store carries its new store here. The figures count only the service orders of stores the caller holds SERVICE_ORDER or REPORTING at. A caller holding SERVICE_ORDER at this store opens the whole case here; REPORTING alone does not open it.","type":"string","pattern":"^[A-Za-z0-9-_]+"},"serviceNumber":{"type":"string","description":"The running service number the service order is known by."},"title":{"type":"string","description":"What the service order is about, as it is shown in a list."},"createdAt":{"type":"string","format":"date-time","description":"When the service order was registered. This is what it is aged by."}}}},"parameters":{"serviceOrderStatsFromDateQuery":{"name":"fromDate","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"The start of the period the figures are measured over (inclusive). The date names a day in the tenant's timezone. It applies to the period figures, and each endpoint states which of its figures those are. The figures that count open service orders always describe how things stand right now, whatever period was asked for.\nThe period is not capped. Every figure is computed live from the event history on each request, over whatever period is asked for, so a full year is asked for exactly the way a single week is.\nISO 8601 date format: YYYY-MM-DD, e.g. 2026-01-01."},"serviceOrderStatsToDateQuery":{"name":"toDate","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"The end of the period the figures are measured over (inclusive). The date names a day in the tenant's timezone. It applies to the period figures, and each endpoint states which of its figures those are. The figures that count open service orders always describe how things stand right now, whatever period was asked for.\nThe period is not capped. Every figure is computed live from the event history on each request, over whatever period is asked for, so a full year is asked for exactly the way a single week is.\nISO 8601 date format: YYYY-MM-DD, e.g. 2026-01-31."},"serviceOrderStatsStoreUidsQuery":{"name":"storeUids","in":"query","required":false,"schema":{"items":{"$ref":"#/components/schemas/UID"},"type":"array"},"description":"Narrow every figure to the stores that own the service orders — the stores the work sits with and where the customers collect. This is the owning store, not the store a service order was taken in at, and the two differ whenever a service order has been moved between stores. Leave it out to get every store the caller holds SERVICE_ORDER or REPORTING at — every store of the tenant for a tenant-wide holder, the organization's stores for an organization holder, the assigned stores for a store-level holder, the two permissions adding up. Naming a store the caller holds neither SERVICE_ORDER nor REPORTING at is not refused and adds nothing: storeUids narrows within the caller's stores and never widens them. A storeUid naming no store of the tenant answers 400."}}},"paths":{"/tenants/{tenantUid}/serviceorders/stats":{"get":{"summary":"Get service order statistics","tags":["Service"],"responses":{"200":{"$ref":"#/components/responses/ServiceOrderStatsResponse"}},"operationId":"get-serviceorders-stats","description":"Get the numbers behind the service manager dashboard: how the open service orders are spread across the states, how much open work each user is carrying, how long service orders take to get through and where the time goes, how often the promised date is missed, which weekdays the work comes in on, how the job types compare, and which open service orders have been waiting longest. Every figure is computed from the service orders' event history, so the numbers say the same thing the timelines do. avgWorkOpenDays also reads the stores' openDays and serviceCountWeekendsAsWorkingDays and the holiday calendar as they stand at the request.\nThe period given by fromDate and toDate applies to the period figures: completedCount, avgTurnaroundDays, avgActiveTurnaroundDays, avgQueueDays, avgWorkDays, avgWorkOpenDays, avgPickupDays, overdueRate and serviceJobTypes all read the service orders completed within the period, and registeredCount and registrationsByWeekday read the ones registered within it. Completed means reached COMPLETE — a cancelled service order takes no part in the period figures, and a reopened one counts in the period of its latest completion. openByState, workload and oldestOpen are not scoped by it: they always describe the service orders that are open right now. Asking without a period still returns those three in full.\nThe period is not capped. Every figure is computed live from the event history on each request, over whatever period is asked for, so a year is asked for exactly the way a week is.\nstoreUids narrows everything, the open figures as well as the period figures, to the stores that own the service orders — the stores the work sits with and where the customers collect. That is the owning store, not the store a service order was taken in at; the two differ whenever a service order has been moved between stores. Left out, every store the caller holds SERVICE_ORDER or REPORTING at is counted.\nThis endpoint answers for the caller's stores as a whole, or for the stores named in storeUids taken together. Compare the stores against each other, for a store comparison or a top or bottom list, through the per-store service order statistics endpoint.\nThe dashboard's tiles and saved-list cards are not read from here. Those come from the service order counts endpoint, which counts whatever filters each of them stands for.\nThe figures key on the store that owns a service order, never on the store it was taken in at: a case that has moved counts for the store it moved to, and for no other. Being able to read a case from another store, the store it was taken in at included, does not make it that store's work here. The figures count only the service orders owned by the stores the caller holds SERVICE_ORDER or REPORTING at — every store of the tenant for a tenant-wide holder, the organization's stores for an organization holder, the assigned stores for a store-level holder, the two permissions adding up — because a figure is a store's work, not a case to find; the tenant-level service order search reaches further, to every service order of the tenant, for a caller holding SERVICE_ORDER.\nA caller holding REPORTING and not SERVICE_ORDER is answered every figure, workload and oldestOpen included, exactly as a caller holding SERVICE_ORDER at the same stores is. A caller holding neither, a user with no role assignments included, is refused with a 403. Opening a service order oldestOpen names through get-serviceorders-by-id asks for SERVICE_ORDER, so a caller holding REPORTING alone sees the entry and is refused on opening it.\n\nRequired permissions: SERVICE_ORDER,REPORTING","parameters":[{"$ref":"#/components/parameters/serviceOrderStatsFromDateQuery"},{"$ref":"#/components/parameters/serviceOrderStatsToDateQuery"},{"$ref":"#/components/parameters/serviceOrderStatsStoreUidsQuery"}]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flowretail.com/docs/developers/api-documentation/service/get-service-order-statistics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
