> ## Documentation Index > Fetch the complete documentation index at: https://docs.narrative.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a cost forecast for a subscription > Create a cost forecast for a subscription, taking into account data already processed for the subscription. ## OpenAPI ````yaml https://docs-cdn.narrative.io/api-reference/main/openapi.json post /data-shops/subscriptions/{subscription_id}/cost-forecasts openapi: 3.1.1 info: contact: email: support@narrative.io name: Narrative Support url: https://www.narrative.io termsOfService: https://www.narrative.io/legal/terms-of-service x-logo: url: >- https://cdn.narrative.io/images/company-logos/prod/narrative-logo-text-white.svg backgroundColor: rgb(9, 34, 166) altText: Narrative Logo description: >- The [Narrative Data Collaboration Platform](https://app.narrative.io) API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. The current version is a pre-release beta. It may result in unexpected behavior and there may be breaking changes in future releases up to the 1.0 release. title: Narrative Data Collaboration Platform API version: 2.4.x servers: - url: https://api-dev.narrative.io - url: https://api.narrative.io security: [] tags: - name: Access Rules description: >- Access rules let data providers control who can purchase their data and the terms of purchase. The `access-rules` API allows you to manage access rules for your datasets. Related guides: - [What is an access rule?](https://kb.narrative.io/access-rules) - name: Agent Conversations description: >- Build LLM-driven workflows that can call MCP tools, ask the caller for input, and return structured answers. A conversation pins a model, a system prompt, and a tool catalog. Each run sends the model a user message (or a batch of tool outputs from a previously-paused run); the model decides whether to answer directly, call a server-side tool (resolved by the platform via Model Context Protocol), or call a client-side tool (which pauses the run with `requires_action` and waits for the caller to reply). Related guides: - [Agent Conversations Reference](https://docs.narrative.io/reference/architecture/agent-conversations) - [Error catalog](https://docs.narrative.io/reference/architecture/agent-conversations/errors/conversation-not-found) - name: MCP Connections description: >- Connect external (non-Narrative) MCP servers so agent runs can call their tools with the calling user's own OAuth authorization. A connection is created interactively: `POST /mcp-connections` runs OAuth discovery and Dynamic Client Registration against the server and returns a consent URL; the user authorizes in a browser; the authorization server redirects to `GET /mcp-connections/callback`, which finishes the token exchange and marks the connection `connected`. Tokens are stored encrypted and used server-side — they are never returned by the API. Once connected, reference the connection by id from an agent run's `mcp_servers[].connection_id`. - name: App Invites description: >- App invites allow applications to create one-time, shareable links on behalf of their users. These links enable users to invite third parties who do not have a Narrative account to perform actions within the application. For example, a Narrative user can send an invite link to a third party who then completes a Pinterest OAuth flow and creates a connector profile in the inviter's account, allowing the inviter to deliver audience data to the third party's Pinterest account without the third party needing a Narrative account. This API is intended to be used by applications (via app client credentials) to create and manage invites on behalf of their users, which can then be shared with invitees. - name: Apps description: >- Apps are applications bundled with a UI that can perform various actions on behalf of a user utilizing the Narrative API. Related guides: - [Building a Narrative Native App](https://www.narrative.io/knowledge-base/how-to-guides/building-a-narrative-native-app) - name: Access Tokens description: API Access Token management - name: Attributes description: >- An attribute models a standardized data point available for sale on the Narrative marketplace. Narrative automatically turns data points from provider datasets into attributes so that buyers can purchase well-formed, standardized data from any supplier on the marketplace. - name: Auth description: >- API token is a crucial step for developers to securely authenticate requests to the Narrative API Related guides: - [How to Create an API Token](https://www.narrative.io/knowledge-base/how-to-guides/understanding-narratives-apis/create-an-api-token) - name: Authentication description: User login and registration - name: Billings description: Used by Narrative internally to bill customers - name: Companies description: A collection of employees - name: Company Marketing Information description: Useful information related to companies - name: Compute Pools description: >- Compute pools represent compute resources (e.g. Snowflake warehouses) provisioned within a data plane. Companies can manage and share compute pools, assign them to jobs, and set a default compute pool on data planes. - name: Connections description: Associations between connectors and datasets - name: Data Shops description: |- Self-hosted website to sell your data Related guides: - [Setting up your datashop](https://www.narrative.io/knowledge-base/how-to-guides/shop-builder/settting-up-your-data-shop) - name: Data Streams description: >- The `data-stream` API endpoints allows one to create and update data-streams. Additionally the endpoints allow finding data-streams using free text search. A few of the endpoints are behind authorization. Update endpoint allows a client to post an edited data-stream document as is, without having to change its shape. The API ensures that only certain fields are allowed to be modified. Attempts to modify fields not up for client modifications are ignored. Related guides: - [What is a data stream?](https://kb.narrative.io/what-is-a-data-stream) - name: Contracts description: Contracts related APIs - name: Datasets description: >- Any kind of data, in any schema, can be pushed into the Narrative Data Collaboration Platform as a dataset exactly as it is stored in your own system. The `datasets` API allows you to manage your datasets. - name: Destinations description: >- Destinations associate a subscription to a profile. Optionally, ad-hoc quick settings can be configured to a destination. Those quick settings have to match the format defined on the app manifest. - name: Installations description: Installations of Applications for a profile - name: Jobs description: >- Jobs represent an operation done on a given data plane. All jobs today are tied to a query that represents a forecast or a materialized view. The jobs API provides an interface for interacting with the jobs table, which stores various operations involving reading or writing data. This API allows users to retrieve detailed information about specific jobs, including cost forecasts, data forecasts, NQL forecasts and materialized views. - name: Mappings description: >- A mapping is a transformation from a dataset to an attribute. Defining a mapping between a dataset and an attribute makes the dataset eligible to participate in subscriptions where a buyer is purchasing the target attribute. - name: Model Inference description: Model Inference - name: Models description: >- Machine learning models for training and inference. Models can be stored in HuggingFace or Narrative repositories and have configurable collaborator permissions for training and inference access. The `models` API allows you to list, retrieve, and update models accessible to your company. - name: NQL description: >- Narrative Query Language (NQL) is a specialized, SQL-inspired language designed to query and manipulate data within the Narrative platform. While it looks and feels much like standard SQL, it offers extended functionality and syntax that let you leverage platform-specific features—such as referencing datasets by their IDs, creating materialized views, or generating forecasts—without having to manage the complexities of different query engines behind the scenes. NQL queries can ultimately compile down to multiple underlying engines (e.g., Snowflake, Spark) to execute your requests efficiently in the Narrative ecosystem. - name: Payment Methods description: Payment methods used to purchase data - name: Products description: Internal routes used to offer datastream as products - name: Profiles description: >- App profiles are associated with an installation. They represent a reference to a configuration that the app can use to save confidential information outside of Narrative's control. Profiles are currently used to configure settings for connector apps. - name: Resources description: >- Narrative gives you access to managed resources, like your own AWS S3 bucket, so that you can effortlessly buy and sell data on the platform. The `resources` API allows you to manage your resources. - name: Schema Inference description: >- The `schema-inference` API analyzes submitted files to automatically infer and return their structure as a dataset schema. - name: Schema Presets description: >- The `schema-presets` API allows you to list the available schema presets, get detailed information about a specific one and manage its life cycle. You can create a schema preset from scratch or create one based on an existing one, administrators can create platform wide available (public) schema preset. - name: Subscriptions description: >- In the Narrative Data Collaboration Platform a subscription represents a set of rules dictating the commercial terms related to the licensing of data. The `subscriptions` API allows you to set and get information about `subscription` objects owned by the authenticated account. - name: Uploads description: >- The `uploads` API allows you to send files to Narrative and use them to perform tasks like creating a list or adding data to a dataset. - name: Usage description: >- The `usage` API enables the recording of usage events associated with a product. - name: Workflows description: >- The `workflows` API allows you to create, schedule, trigger, and archive workflows. Workflows are defined using a serverlessworkflow YAML specification. paths: /data-shops/subscriptions/{subscription_id}/cost-forecasts: post: tags: - Subscriptions summary: Create a cost forecast for a subscription description: >- Create a cost forecast for a subscription, taking into account data already processed for the subscription. parameters: - $ref: '#/components/parameters/SubscriptionId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CostForecastResponse' security: - BearerAuth: [] components: parameters: SubscriptionId: name: subscription_id in: path required: true description: Unique identifier for a subscription. schema: type: string format: uuid schemas: CostForecastResponse: type: object required: - company_id - cost - created_at - details properties: id: type: string format: UUID description: >- Unique identifier for the cost forecast. Empty if no cost forecast was created due to the subscriptions constraints resulting in no matches. cost: $ref: '#/components/schemas/ScanCostEstimate' company_id: type: integer description: >- Unique identifier for the company to which the cost forecast belongs. created_at: description: ISO-8601 timestamp indicating when the cost forecast was created type: string details: description: The set of constraints to which the cost forecast applies. allOf: - $ref: '#/components/schemas/Details' subscription_id: type: string format: UUID description: >- Unique identifier of the subscription for which the cost forecast was created. Empty if the cost forecast is not associated with a subscription. example: id: 9cdd4b69-82cb-4454-aedf-197bc3930b44 company_id: 1 cost: rows: 26565354859246 size: 1299135691639572 sources: - source: type: dataset dataset_id: 192 rows: 26565354859246 size: 1299135691639572 created_at: '2021-11-26T20:20:13.909581Z' details: type: marketplace company_constraint: type: exclusion company_ids: - 56 data_rules: attributes: - attribute_id: 2 fields: - field: event_timestamp filter: recency: P30D exported: true optional: false - attribute_id: 1 fields: - field: unique_id.type filter: type: include list: - idfa - adid exported: true - field: unique_id.value filter: include_only_if_not_null_filter exported: true optional: false - attribute_id: 11 fields: - field: ip_address filter: include_only_if_not_null_filter exported: true optional: false frequency_filter: attribute_references: - attribute_id: 1 column_names: - unique_id.type - unique_id.value min_inclusive: 2 pricing: micro_cents_usd: 10000000 request_source: type: api_user company_id: 1 user_id: 1 subscription_id: null ScanCostEstimate: type: object description: >- An estimate of the "cost" of servicing a set of subscription constraints. Cost has two components: - The number of rows which must be read in order to find data which matches the subscription constraints. - An estimate of the "size" of those rows in bytes. Note: the number of rows reported in the cost is **not** an estimate of the number of rows which will be purchased as part of a subscription using the given constraints. required: - rows - size - sources properties: rows: type: integer description: >- The number of rows which must be read in order to find data which matches the constraints. size: type: number description: >- An approximation of the number of bytes of data which much be read to find data which matches the constraints. sources: type: array description: The data sources which must be read along with associated costs. items: type: object required: - source - rows - size properties: source: oneOf: - type: object description: A dataset source. required: - type - dataset_id properties: type: type: string description: Discriminator indicating that the source is a dataset. enum: - dataset dataset_id: type: integer description: Unique identifier for the dataset. - type: object description: A non-dataset source. required: - type - name properties: type: type: string description: >- Discriminator indicating that the source is a non-dataset table storing information relevant to the fulfillment of the constraints. enum: - table name: type: string description: The data source's name. rows: type: integer description: The number of rows which must be read from the data source. size: type: number description: >- An approximation of the number of bytes which must be read from the data source. Details: oneOf: - $ref: '#/components/schemas/DataStreamDetails' - $ref: '#/components/schemas/MarketplaceDetails' DataStreamDetails: type: object required: - type - data_rules - data_shop_id - data_stream_company_id - data_stream_content - data_stream_id - data_stream_name - data_stream_slug properties: type: type: string description: Details of a purchase of a data stream. enum: - data_stream data_rules: $ref: '#/components/schemas/DataRules' data_shop_id: $ref: '#/components/schemas/HostnameOrDataShopId' description: >- The hostname or uuid of the data shop on which the data stream was purchased. data_stream_company_id: type: integer description: >- The unique identifier of the company from which the data stream was purchased. data_stream_content: $ref: '#/components/schemas/Content' data_stream_id: type: string format: uuid description: Unique identifier for the data stream being purchased. data_stream_name: $ref: '#/components/schemas/Name' data_stream_slug: $ref: '#/components/schemas/Slug' offer: $ref: '#/components/schemas/Offer' MarketplaceDetails: type: object required: - type - data_rules - pricing properties: type: type: string description: Details of a purchase of a data stream. enum: - marketplace company_constraint: $ref: '#/components/schemas/CompanyConstraint' dataset_constraint: $ref: '#/components/schemas/DatasetConstraint' data_rules: $ref: '#/components/schemas/DataRules' pricing: $ref: '#/components/schemas/Subscription_Pricing' DataRules: description: >- Data rules capture the rules around how the data is handled within a data stream. The starting point might be an already predefined and active dataset(s) or the global data attributes on the platform. Data rules might apply further filtering on the data being ingested and exported through the stream. type: object properties: column_sets: type: array minLength: 1 items: $ref: '#/components/schemas/ColumnSet' attributes: type: array minLength: 1 items: $ref: '#/components/schemas/Attributes' deduplication: $ref: '#/components/schemas/Deduplication' frequency_filter: $ref: '#/components/schemas/FrequencyFilter' dataset_filter: $ref: '#/components/schemas/DatasetFilter' HostnameOrDataShopId: oneOf: - $ref: '#/components/schemas/Hostname' - $ref: '#/components/schemas/UUID' Content: type: object properties: description: $ref: '#/components/schemas/DataStream_Description' icon: $ref: '#/components/schemas/Icon' sections: type: array items: type: object required: - description Name: type: string format: trimmed-non-empty description: A name. minLength: 1 Slug: type: string pattern: ^[a-zA-Z0-9-_.:]+$ description: The DataStream's slug. Used for SEO/URLs. minLength: 1 Offer: type: object properties: id: $ref: '#/components/schemas/UUID' channel: $ref: '#/components/schemas/SalesChannel' licensing: $ref: '#/components/schemas/Licensing' pricing: $ref: '#/components/schemas/Pricing' shops: type: array items: $ref: '#/components/schemas/HostnameOrDataShopId' required: - id - channel - licensing - pricing CompanyConstraint: type: object description: >- A constraint describing which companies the subscription should or should not purchase from. properties: type: type: string description: >- - `inclusion`: means this subscription should purchase from datasets provided by only the companies specified in `company_ids`. - `exclusion`: means this subscription should from datasets provided by any company _except_ those specified in `company_ids`. enum: - inclusion - exclusion company_ids: type: array description: The companies to which the constraint applies. items: type: integer required: - type - company_ids DatasetConstraint: type: object description: >- A constraint describing which datasets the subscription should or should not purchase from. properties: type: type: string description: >- - `inclusion`: means this subscription should purchase from datasets provided by only the datasets specified in `dataset_ids`. - `exclusion`: means this subscription should purchase from datasets provided by any dataset _except_ those specified in `dataset_ids`. - `all`: means this subscription should purchase from datasets from any dataset, including your own datasets. This option was added for backward compatibility to allow targeting your own datasets. enum: - inclusion - exclusion - all dataset_ids: type: array description: >- The datasets to which the constraint applies. Required when type is `inclusion` or `exclusion`. items: type: integer required: - type Subscription_Pricing: type: object properties: micro_cents_usd: type: integer description: >- The maximum price you are willing to pay per row in microcents USD. Data from providers that costs more than your specified price will not be purchased as part of the subscription. Some useful conversions: - 1 cent = 1000000 microcents - 1 dollar = 100000000 microcents If you wanted to spend a max of $1 USD per 1000 rows, then you'd set `micro_cents_usd` to `100000`. ColumnSet: type: object properties: dataset_id: $ref: '#/components/schemas/LongId' description: A valid existing active dataset id. fields: type: array minLength: 1 items: $ref: '#/components/schemas/ColumnWithFilterAndExport' required: - dataset_id - fields Attributes: type: object properties: attribute_id: $ref: '#/components/schemas/LongId' fields: type: array minLength: 1 items: $ref: '#/components/schemas/ColumnWithFilterAndExport' optional: type: boolean required: - attribute_id - fields - optional Deduplication: type: object properties: period: $ref: '#/components/schemas/Period' column_references: type: array minLength: 1 items: $ref: '#/components/schemas/ColumnReference' attribute_references: type: array minLength: 1 items: $ref: '#/components/schemas/AttributeReference' required: - period FrequencyFilter: type: object properties: column_references: type: array minLength: 1 items: $ref: '#/components/schemas/ColumnReference' attribute_references: type: array minLength: 1 items: $ref: '#/components/schemas/AttributeReference' min_inclusive: type: integer format: int32 max_inclusive: type: integer format: int32 DatasetFilter: description: >- `DatasetFilter` allows the use of an uploaded Dataset to filter data that is purchased as part of a `Subscription`. type: object properties: dataset_id: $ref: '#/components/schemas/LongId' description: Id for an existing active dataset that is owned by the calling user. attribute: type: object properties: attribute_id: $ref: '#/components/schemas/LongId' field: $ref: '#/components/schemas/FieldPath' inclusion: $ref: '#/components/schemas/InclusionType' Hostname: type: string format: trimmed-non-empty description: A shops hostname. minLength: 1 UUID: type: string format: uuid DataStream_Description: type: string format: trimmed-non-empty description: The DataStream's name. minLength: 1 Icon: type: string format: trimmed-non-empty description: The icon link. minLength: 1 SalesChannel: type: string enum: - data_streams_market - data_shop Licensing: type: object properties: period: $ref: '#/components/schemas/Period' license: type: object properties: name: $ref: '#/components/schemas/Name' required: - name required: - period - license Pricing: type: object properties: type: type: string enum: - per_record - max_price_per_record micro_cents_usd: $ref: '#/components/schemas/PriceInMicroCent' required: - type - micro_cents_usd LongId: type: integer format: int64 ColumnWithFilterAndExport: type: object properties: field: $ref: '#/components/schemas/FieldPath' filter: oneOf: - $ref: '#/components/schemas/IncludeAllValuesIncludingNullsFilter' - $ref: '#/components/schemas/IncludeOnlyIfNotNullFilter' - $ref: '#/components/schemas/EnumFilter' - $ref: '#/components/schemas/IntervalFilter' - $ref: '#/components/schemas/TimestampFilter' - $ref: '#/components/schemas/SparkSqlConstraintFilter' exported: type: boolean description: >- Is this column exported in the data-stream? A column/field might be needed for filtering purposes and not always a part of the exposed data-stream. required: - field - exported Period: type: string format: java.time.Period description: >- A date-based amount of time in the ISO-8601 calendar system, such as '2 years, 3 months and 4 days'. minLength: 1 ColumnReference: type: object properties: dataset_id: $ref: '#/components/schemas/LongId' description: A valid existing active dataset id. column_names: type: array minLength: 1 items: $ref: '#/components/schemas/FieldPath' required: - dataset_id - column_names AttributeReference: type: object properties: attribute_id: $ref: '#/components/schemas/LongId' column_names: type: array minLength: 1 items: $ref: '#/components/schemas/FieldPath' required: - attribute_id - column_names FieldPath: description: A RFC-6901 JSON pointer to a Dataset field. type: string example: /id/value InclusionType: type: string enum: - include - exclude description: Include or exclude values in an enum filter. PriceInMicroCent: type: integer format: int64 IncludeAllValuesIncludingNullsFilter: type: string enum: - include_all_values_including_nulls_filter description: >- This filter enforces inclusion of all values including nulls, i.e. it acts as if no filter is applied at all. IncludeOnlyIfNotNullFilter: type: string enum: - include_only_if_not_null_filter description: >- This filter excludes null values, i.e. if this filter applies to a given column in a row then the entire row is excluded from the stream. EnumFilter: type: object properties: type: $ref: '#/components/schemas/InclusionType' list: type: array minLength: 1 items: type: string example: type: include list: - this - that - that too - some more IntervalFilter: type: object properties: min: $ref: '#/components/schemas/IntervalEnd' max: $ref: '#/components/schemas/IntervalEnd' description: One of the two 'min' or 'max' should be defined. example: min: type: exclusive value: timestamp01 max: type: exclusive value: timestamp02 TimestampFilter: type: object properties: recency: $ref: '#/components/schemas/Period' from: $ref: '#/components/schemas/IntervalEnd' to: $ref: '#/components/schemas/IntervalEnd' example: recency: P30D from: type: exclusive value: timestamp01 to: type: exclusive value: timestamp02 SparkSqlConstraintFilter: type: object properties: expressions: type: array minLength: 1 items: $ref: '#/components/schemas/Expression' required: - expressions IntervalEnd: type: object properties: type: $ref: '#/components/schemas/IntervalType' value: type: string description: >- An interval bounds, captured as a string value. For example, numbers (ints, longs and doubles) and boolean would be captured as "-1", "0.0", "true" required: - type - value Expression: type: string description: >- A raw Spark SQL expression potentially containing a placeholder token, $this, that needs to be resolved prior to execution. IntervalType: type: string enum: - inclusive - exclusive description: Whether an interval end includes or excludes the end itself. securitySchemes: BearerAuth: type: http scheme: bearer ````