--- title: "(EXPERIMENTAL) Generate a document takeaway" method: POST path: "/api/v1/ai/workspaces/{workspace_id}/takeaway" tags: ["Document Takeaway"] --- # (EXPERIMENTAL) Generate a document takeaway `POST /api/v1/ai/workspaces/{workspace_id}/takeaway` ## Request - Base URL: `https://www.gooddata.ai` - URL: `https://www.gooddata.ai/api/v1/ai/workspaces/{workspace_id}/takeaway` - Auth: none declared Note: This API is an experimental and is going to change. Please, use it accordingly. Writes a short takeaway for one slot of a document, based on the data of the given visualizations. The text is written as the given AI Hub agent, or as the user's default agent. Without either agent, the request fails. When no visualization has data, the response sets `noData`, carries no text and no model is called. ## Path parameters - `workspace_id` string, required ## Request body - TakeawayRequest - `agentId` string: The AI Hub agent that writes the takeaway. Omit it to use the user's default agent. - `data` TakeawayDataRequest, required - `filterContext` union[], required: AFM filters in the same shape consumed by the AFM execute endpoint, applied to every visualization on top of its stored filters. Send `[]` to apply no request filters. Each layer is merged on top of the one below it: attribute, ranking and inline filters are added and all apply together; a date filter replaces the lower layer's date filter on the same date dataset; a measure value filter replaces the lower layer's measure value filter on the same measure. - union - PositiveAttributeFilter: Filter able to limit element values by label and related selected elements. - `positiveAttributeFilter` PositiveAttributeFilterBody, required - `applyOnResult` boolean - `in` AttributeFilterElements, required: Filter on specific set of label values. - … - `label` union, required - … - `localIdentifier` string - `usesArbitraryValues` boolean - NegativeAttributeFilter: Filter able to limit element values by label and related selected negated elements. - `negativeAttributeFilter` NegativeAttributeFilterBody, required - `applyOnResult` boolean - `label` union, required - … - `localIdentifier` string - `notIn` AttributeFilterElements, required: Filter on specific set of label values. - … - `usesArbitraryValues` boolean - MatchAttributeFilterInput - `matchAttributeFilter` MatchAttributeFilterBodyInput, required - `applyOnResult` boolean - `caseSensitive` boolean - `label` union, required - … - `literal` string, required - `localIdentifier` string - `matchType` 'STARTS_WITH' | 'ENDS_WITH' | 'CONTAINS', required - `negate` boolean - AbsoluteDateFilter: A datetime filter specifying exact from and to values. - `absoluteDateFilter` AbsoluteDateFilterBody, required - `applyOnResult` boolean - `dataset` AfmObjectIdentifier, required: ObjectIdentifier with `identifier` wrapper. This serves to distinguish MD object identifiers in AFM request from local identifiers. - … - `emptyValueHandling` 'INCLUDE' | 'EXCLUDE' | 'ONLY' - `from` string, required - `localIdentifier` string - `to` string, required - RelativeDateFilter: A date filter specifying a time interval that is relative to the current date. For example, last week, next month, and so on. Field dataset is representing qualifier of date dimension. The 'from' and 'to' properties mark the boundaries of the interval. If 'from' is omitted, all values earlier than 'to' are included. If 'to' is omitted, all values later than 'from' are included. It is not allowed to omit both. - `relativeDateFilter` RelativeDateFilterBody, required - `applyOnResult` boolean - `boundedFilter` BoundedFilter: Bounding filter for this relative date filter. This can be used to limit the range of the relative date filter to a specific date range. - … - `dataset` AfmObjectIdentifier, required: ObjectIdentifier with `identifier` wrapper. This serves to distinguish MD object identifiers in AFM request from local identifiers. - … - `emptyValueHandling` 'INCLUDE' | 'EXCLUDE' | 'ONLY' - `from` integer, required - `granularity` 'SECOND' | 'SECOND_OF_MINUTE' | 'SECOND_OF_DAY' | 'MINUTE' | 'MINUTE_OF_DAY' | 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR' | 'MINUTE_OF_HOUR' | 'HOUR_OF_DAY' | 'DAY_OF_WEEK' | 'DAY_OF_MONTH' | 'DAY_OF_QUARTER' | 'DAY_OF_YEAR' | 'WEEK_OF_YEAR' | 'MONTH_OF_YEAR' | 'QUARTER_OF_YEAR' | 'FISCAL_DAY_OF_FISCAL_WEEK' | 'FISCAL_DAY_OF_FISCAL_MONTH' | 'FISCAL_DAY_OF_FISCAL_QUARTER' | 'FISCAL_DAY_OF_FISCAL_SEMESTER' | 'FISCAL_DAY_OF_FISCAL_YEAR' | 'FISCAL_WEEK' | 'FISCAL_WEEK_OF_FISCAL_MONTH' | 'FISCAL_WEEK_OF_FISCAL_QUARTER' | 'FISCAL_WEEK_OF_FISCAL_SEMESTER' | 'FISCAL_WEEK_OF_FISCAL_YEAR' | 'FISCAL_MONTH' | 'FISCAL_MONTH_OF_FISCAL_QUARTER' | 'FISCAL_MONTH_OF_FISCAL_SEMESTER' | 'FISCAL_MONTH_OF_FISCAL_YEAR' | 'FISCAL_QUARTER' | 'FISCAL_QUARTER_OF_FISCAL_SEMESTER' | 'FISCAL_QUARTER_OF_FISCAL_YEAR' | 'FISCAL_SEMESTER' | 'FISCAL_SEMESTER_OF_FISCAL_YEAR' | 'FISCAL_YEAR', required - `localIdentifier` string - `to` integer, required - AllTimeDateFilter: An all-time date filter that does not restrict by date range. Controls how rows with empty (null/missing) date values are handled. - `allTimeDateFilter` AllTimeDateFilterBody, required - `applyOnResult` boolean - `dataset` AfmObjectIdentifier, required: ObjectIdentifier with `identifier` wrapper. This serves to distinguish MD object identifiers in AFM request from local identifiers. - … - `emptyValueHandling` 'INCLUDE' | 'EXCLUDE' | 'ONLY' - `granularity` 'SECOND' | 'SECOND_OF_MINUTE' | 'SECOND_OF_DAY' | 'MINUTE' | 'MINUTE_OF_DAY' | 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR' | 'MINUTE_OF_HOUR' | 'HOUR_OF_DAY' | 'DAY_OF_WEEK' | 'DAY_OF_MONTH' | 'DAY_OF_QUARTER' | 'DAY_OF_YEAR' | 'WEEK_OF_YEAR' | 'MONTH_OF_YEAR' | 'QUARTER_OF_YEAR' | 'FISCAL_DAY_OF_FISCAL_WEEK' | 'FISCAL_DAY_OF_FISCAL_MONTH' | 'FISCAL_DAY_OF_FISCAL_QUARTER' | 'FISCAL_DAY_OF_FISCAL_SEMESTER' | 'FISCAL_DAY_OF_FISCAL_YEAR' | 'FISCAL_WEEK' | 'FISCAL_WEEK_OF_FISCAL_MONTH' | 'FISCAL_WEEK_OF_FISCAL_QUARTER' | 'FISCAL_WEEK_OF_FISCAL_SEMESTER' | 'FISCAL_WEEK_OF_FISCAL_YEAR' | 'FISCAL_MONTH' | 'FISCAL_MONTH_OF_FISCAL_QUARTER' | 'FISCAL_MONTH_OF_FISCAL_SEMESTER' | 'FISCAL_MONTH_OF_FISCAL_YEAR' | 'FISCAL_QUARTER' | 'FISCAL_QUARTER_OF_FISCAL_SEMESTER' | 'FISCAL_QUARTER_OF_FISCAL_YEAR' | 'FISCAL_SEMESTER' | 'FISCAL_SEMESTER_OF_FISCAL_YEAR' | 'FISCAL_YEAR' - `localIdentifier` string - RankingFilter: Filter the result on top/bottom N values according to given metric(s). - `rankingFilter` RankingFilterBody, required - `applyOnResult` boolean - `dimensionality` union[] - … - `localIdentifier` string - `measures` union[], required - … - `operator` 'TOP' | 'BOTTOM', required - `value` integer, required - ComparisonMeasureValueFilter: Filter the result by comparing specified metric to given constant value, using given comparison operator. - `comparisonMeasureValueFilter` ComparisonMeasureValueFilterBody, required - `applyOnResult` boolean - `dimensionality` union[] - … - `localIdentifier` string - `measure` union, required - … - `operator` 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'EQUAL_TO' | 'NOT_EQUAL_TO', required - `treatNullValuesAs` number - `value` number, required - RangeMeasureValueFilter: Filter the result by comparing specified metric to given range of values. - `rangeMeasureValueFilter` RangeMeasureValueFilterBody, required - `applyOnResult` boolean - `dimensionality` union[] - … - `from` number, required - `localIdentifier` string - `measure` union, required - … - `operator` 'BETWEEN' | 'NOT_BETWEEN', required - `to` number, required - `treatNullValuesAs` number - CompoundMeasureValueFilter: Filter the result by applying multiple comparison and/or range conditions combined with OR logic. If conditions list is empty, no filtering is applied (all rows are returned). - `compoundMeasureValueFilter` CompoundMeasureValueFilterBody, required - `applyOnResult` boolean - `conditions` union[], required - … - `dimensionality` union[] - … - `localIdentifier` string - `measure` union, required - … - `treatNullValuesAs` number - InlineFilterDefinition: Filter in form of direct MAQL query. - `inline` InlineFilterDefinitionBody, required - `applyOnResult` boolean - `filter` string, required - `localIdentifier` string - `visualizations` union[], required: Visualizations the takeaway is based on. Every one must load, or the request fails. An item is a visualization ID or an object with `visualizationId` and its own `filters`. A visualization ID gets its stored filters and `filterContext` only. - union - string - VisualizationPlacementRequest: One placement of a visualization, summarized under its own filters. - `filters` union[], required: AFM filters for this placement only. Layers, lowest first: the visualization's stored filters, `filterContext`, then these filters. Send `[]` to apply no own filters. Each layer is merged on top of the one below it: attribute, ranking and inline filters are added and all apply together; a date filter replaces the lower layer's date filter on the same date dataset; a measure value filter replaces the lower layer's measure value filter on the same measure. - union - … - `visualizationId` string, required - `instructions` TakeawayInstructionsRequest - `document` string: What the whole document is for. Applies to every slot of the document. - `formatHint` string: The preferred shape of the text. Yields to `document` and `slot`. - `slot` string: What this takeaway must say. Wins over `document` and `formatHint` when they conflict. - `maxCharacters` integer: Upper limit for the length of the takeaway, in characters. ## Response `200` Successful Response - TakeawayResponse - `agentId` string, required: The AI Hub agent that the takeaway is written as. - `contextOmitted` string[], required: The context parts that did not fully load because a lookup failed or timed out, wholly or partly. The takeaway uses what did load. A part that configuration switches off is never listed. - `generatedAt` string, date-time, required - `noData` boolean, required: `true` when no visualization has data for the filters. Then no text is written and nothing is charged. - `takeaway` string, required: The takeaway text. It is `null` when `noData` is `true`. ## Other responses - `400`: The call context is missing organization or user, no LLM provider is configured, or no agent is named and the user has no default agent. The last case carries the code `NO_AVAILABLE_AGENT`. LLM-endpoint failures also carry a `code` field naming the error class. - `403`: Sharing data with the LLM is disabled for this organization. - `404`: The feature is not enabled for this organization, the agent does not exist or is not available to the user, or a visualization does not exist or is not available to AI. - `422`: The request body is invalid, for example `maxCharacters` is out of range. Or the execution backend rejected the request of a visualization, for example for an invalid filter. Then `detail` is a message that names the visualization and gives the reason. - `429`: AI query limit exceeded. - `502`: A visualization failed to execute for a reason other than the request, or the upstream LLM provider failed. The body carries a `detail` message or a `code` field naming the error class. - `504`: The takeaway did not finish in time. The body carries a `detail` message. --- [API](https://skmtc.dev/gooddata/apis/gooddata-cn-oapi-all-api.md) - [All operations](https://skmtc.dev/gooddata/apis/gooddata-cn-oapi-all-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gooddata/apis/gooddata-cn-oapi-all-api/revisions/c728ef303bfb?raw)