Understanding Entities

Quick Overview

Entities are unique identifiers that represent the items you're analyzing or forecasting. They help you organize and track historical results for products, categories, or any other business units.

What Are Entities?

An entity is a unique identifier that represents something you're analyzing through ForecastAPI. Whenever you send data to our API for analysis or forecasting, ForecastAPI automatically creates and tracks an entity based on the identifier you provide.

Think of entities as the central organizing principle for your forecasting data. Each entity represents a unique item in your business—whether that's a product SKU, a category, a business unit, a customer segment, or any other identifiable unit you're tracking over time.

Common Entity Types

Entities can represent various types of business units, depending on your use case:

Products & SKUs

Individual products or stock-keeping units (SKUs). Each unique product identifier becomes an entity, allowing you to track sales forecasts, inventory predictions, and demand patterns for specific items.

Example: "SKU-12345", "PROD-WIDGET-A"

Categories

Product categories or groups. Track aggregate performance across entire product lines or departments to understand broader trends and make strategic decisions.

Example: "electronics", "apparel", "food-beverages"

Business Units

Different divisions, stores, or geographic regions within your organization. Monitor performance and forecast trends for each business unit independently.

Example: "store-nyc-001", "division-north-america"

Custom Units

Any other unique identifier that makes sense for your business—customer IDs, campaign names, project codes, or anything else you need to track and forecast.

Example: "campaign-summer-2024", "project-alpha"

How Entities Work

Automatic Creation

You don't need to manually create entities. When you make an API request to analyze or forecast data, ForecastAPI automatically:

  1. Extracts the identifier from your request
  2. Creates a new entity if one doesn't exist for that identifier
  3. Links the analysis results to that entity
  4. Makes the entity visible in your dashboard

Entity Identifiers

Each entity is uniquely identified by a combination of:

  • Identifier – The unique ID you provide in your API requests (e.g., "SKU-12345")
  • Tenant Context (optional) – An additional context field for multi-tenant setups

This means you can have the same identifier across different tenant contexts, allowing you to manage analyses for multiple clients or subsidiaries separately.

Using the Entities Dashboard

The Entities page in your dashboard provides a centralized view of all entities that have been 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 When the entity was last analyzed or forecasted

Searching Entities

Use the search bar to quickly find specific entities by:

  • Identifier (e.g., searching for "SKU-123" will find all entities with that identifier)
  • Name (if you've provided display names for your entities)
  • Tenant Context (to filter entities by tenant or context)

Pro Tip

Search is performed in real-time as you type, making it easy to filter through large numbers of entities quickly.

Tenant Context Explained

The tenant_context field is an optional parameter that allows you to organize entities across different contexts, particularly useful in multi-tenant scenarios.

Use Cases for Tenant Context

Multi-Tenant SaaS Applications

If you're building a SaaS application that serves multiple customers, you can use tenant_context to separate data for each customer while using the same identifier scheme.

tenant_context: "customer-acme-corp"
identifier: "product-widget-a"

Multi-Brand Organizations

If you manage multiple brands or subsidiaries, use tenant_context to keep each brand's data separate while maintaining consistent product identifiers.

tenant_context: "brand-premium"
identifier: "SKU-12345"

Geographic Segmentation

Track the same product across different regions or markets by using 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'll find summary cards showing:

Total Entities
247

Number of unique entities tracked

Total Analyses
1,834

Combined analyses across all entities

Unique Types
5

Different entity type categories

Best Practices

Use Consistent Identifiers

Maintain consistent identifier formats across your API requests. For example, if you use "SKU-12345" format, stick with it throughout your application to ensure proper entity tracking.

Leverage Tenant Context

If you're managing multiple brands, customers, or regions, always include the tenant_context in your API requests to keep data properly segmented and organized.

Provide Descriptive Names

When making API requests, include descriptive names (like product names) in addition to identifiers. This makes entities easier to identify in the dashboard.

Monitor Historical Performance

Regularly review your entities dashboard to understand which items are being analyzed most frequently and identify entities that might need attention or reforecasting.

Example API Usage

Here's how entities are created 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:

  1. Create or find an entity with identifier "SKU-WIDGET-2024" and tenant_context "store-nyc-001"
  2. Process the forecast/analysis for this data
  3. Link the results to this entity
  4. Display the entity in your dashboard with analysis count and last activity timestamp

Important Note

Entities are automatically created when you make API requests. You cannot manually create or delete entities through the dashboard—they are always tied to actual analysis requests to ensure data integrity.

Related Resources

API Reference

Learn about the API endpoints and how to include identifiers and tenant context in your requests.

Batch Processing

Process multiple entities at once using our batching API for efficient bulk forecasting.

Need Help?

If you have questions about entities or need assistance with organization strategies, contact our support team.