Understanding Entities.
An entity is a unique identifier for an item you analyze or forecast. Entities help you organize and track historical results for products, categories, or other business units.
What Are Entities?
An entity is a unique identifier for something you analyze through ForecastAPI. When you send data to the API for analysis or a forecast, ForecastAPI creates an entity. It tracks the entity by the identifier you provide.
Entities are the main way to organize your forecasting data. Each entity represents a unique item in your business. The item can be a product SKU, a category, a business unit, a customer segment, or another unit you track over time.
Common Entity Types
Entities can represent different types of business units, depending on your use case:
Use this entity for an individual product or stock-keeping unit (SKU). Each unique product identifier becomes an entity. You can then track sales forecasts, inventory predictions, and demand patterns for specific items.
Example: "SKU-12345", "PROD-WIDGET-A"
Use this entity for a product category or group. Track aggregate performance across product lines or departments to see trends and make decisions.
Example: "electronics", "apparel", "food-beverages"
Use this entity for a division, store, or geographic region in your organization. Monitor performance and forecast trends for each business unit independently.
Example: "store-nyc-001", "division-north-america"
Use this entity for any other unique identifier that fits your business. Examples include customer IDs, campaign names, project codes, or anything else you track and forecast.
Example: "campaign-summer-2024", "project-alpha"
How Entities Work
Automatic Creation
You do not need to create entities manually. When you make an API request to analyze or forecast data, ForecastAPI automatically:
-
Extracts the
identifierfrom your request -
Creates a new entity if none exists for that identifier
-
Links the analysis results to that entity
-
Shows the entity in your dashboard
Entity Identifiers
ForecastAPI identifies each entity by a combination of:
You can use the same identifier across different tenant contexts. This lets you manage analyses for multiple clients or subsidiaries separately.
Using the Entities Dashboard
The Entities page in your dashboard lists every entity you have analyzed or forecasted.
Viewing Your Entities
Navigate to Entities from the sidebar to see:
| Column | Description |
|---|---|
| Identifier | The unique identifier for this entity, along with its optional display name |
| Tenant Context | The tenant or context associated with this entity (if provided) |
| Type | The category or type of entity (e.g., product, category, business unit) |
| Analyses | The total number of analyses performed for this entity |
| Last Activity | The date of the last analysis or forecast for this entity |
Searching Entities
Use the search bar to quickly find specific entities by:
- Identifier (e.g., a search for "SKU-123" finds all entities with that identifier)
- Name (if you have provided display names for your entities)
- Tenant Context (to filter entities by tenant or context)
Search runs in real time as you type, so you can filter large numbers of entities quickly.
Tenant Context Explained
The tenant_context field is an optional parameter.
It lets you organize entities across different contexts, which is useful in multi-tenant scenarios.
Use Cases for Tenant Context
You may build a SaaS application that serves multiple customers. Use tenant_context to separate data for each customer while you keep the same identifier scheme.
tenant_context: "customer-acme-corp"
identifier: "product-widget-a"
If you manage multiple brands or subsidiaries, use tenant_context to keep each brand's data separate. This keeps product identifiers consistent.
tenant_context: "brand-premium"
identifier: "SKU-12345"
Track the same product across different regions or markets. Use tenant_context for the geographic area.
tenant_context: "region-us-west"
identifier: "product-laptop-pro"
Dashboard Summary Statistics
At the bottom of the Entities page, you will find summary cards that show:
The dashboard tracks 247 unique entities.
The dashboard counts 1,834 analyses across all entities.
Your entities use 5 different type categories.
Best Practices
Example API Usage
This example shows how ForecastAPI creates entities through API requests:
{
"identifier": "SKU-WIDGET-2024",
"tenant_context": "store-nyc-001",
"data": [
{ "date": "2024-01-01", "value": 120 },
{ "date": "2024-02-01", "value": 145 },
{ "date": "2024-03-01", "value": 132 }
],
"frequency": "M"
}
When you make this request, ForecastAPI will:
-
Create or find an entity with identifier "SKU-WIDGET-2024" and tenant_context "store-nyc-001"
-
Process the forecast or analysis for this data
-
Link the results to this entity
-
Display the entity in your dashboard with analysis count and last activity timestamp
ForecastAPI creates entities automatically when you make API requests. You cannot create or delete entities manually in the dashboard. Each entity always ties to a real analysis request, which protects data integrity.
Related Resources
If you have questions about entities or need help organizing them, contact our support team.