Skip to content
Log inGet started

API reference

Forecast

The forecast answers “what will we close this period?”: open deals expected to close in a date range, grouped by forecast category, with plain and probability-weighted totals.

Scope
analytics:read
Plan
Analytics hub
Access
Read-only

The forecast object

Values are added as stored, without currency conversion — keep a forecast to one currency, or split it by pipeline.

Attributes

  • periodobject

    The period you asked for.

    • startdate

      First day, inclusive.

    • enddate

      Last day, inclusive.

  • categoriesobject[]

    One entry per category, always in the order commit, best_case, pipeline.

  • totalsobject

    Running totals across categories.

    • commitnumber

      Value of commit deals.

    • best_casenumber

      Value of commit and best_case deals together.

    • weightednumber

      Weighted value of all three categories.

    • pipelinenumber

      Value of all three categories.

    • deal_countinteger

      Deals counted.

  • dealsobject[]

    The deals counted, for drill-down.

    • iduuid

      Deal ID.

    • titlestring

      Deal name.

    • valuenumber

      Amount.

    • currencystring

      ISO 4217 code.

    • probabilityinteger

      Win probability in percent.

    • expected_close_datedate

      Expected close date, inside the period.

    • forecast_categoryenum

      The category it counts in — pipeline when the deal has none.

      One ofcommitbest_casepipeline

    • stagestringNullable

      Name of the deal’s stage; null if the deal is in no pipeline.

    • company_namestringNullable

      Name of the deal’s company.

The forecast object
{
  "period": {
    "start": "2026-10-01",
    "end": "2026-12-31"
  },
  "categories": [
    {
      "category": "commit",
      "deal_count": 2,
      "total_value": 27000,
      "weighted_value": 23400,
      "avg_probability": 85
    },
    {
      "category": "best_case",
      "deal_count": 1,
      "total_value": 24000,
      "weighted_value": 14400,
      "avg_probability": 60
    },
    {
      "category": "pipeline",
      "deal_count": 1,
      "total_value": 36000,
      "weighted_value": 14400,
      "avg_probability": 40
    }
  ],
  "totals": {
    "commit": 27000,
    "best_case": 51000,
    "weighted": 52200,
    "pipeline": 87000,
    "deal_count": 4
  },
  "deals": [
    {
      "id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
      "title": "Northwind Analytics — annual plan",
      "value": 24000,
      "currency": "EUR",
      "probability": 60,
      "expected_close_date": "2026-11-27",
      "forecast_category": "best_case",
      "stage": "Proposal",
      "company_name": "Northwind Analytics"
    },
    {
      "id": "3b5d7f9a-1c3e-4a5c-8e7f-9a1b3c5d7e02",
      "title": "Harbor Logistics — pilot",
      "value": 9000,
      "currency": "EUR",
      "probability": 80,
      "expected_close_date": "2026-10-31",
      "forecast_category": "commit",
      "stage": "Negotiation",
      "company_name": "Harbor Logistics"
    },
    {
      "id": "5d7f9b1c-3e5a-4c7e-9a1b-3c5e7a9b1d14",
      "title": "Fabrikam — renewal",
      "value": 18000,
      "currency": "EUR",
      "probability": 90,
      "expected_close_date": "2026-12-15",
      "forecast_category": "commit",
      "stage": "Negotiation",
      "company_name": "Fabrikam"
    },
    {
      "id": "7f9b1d3e-5a7c-4e9a-8b1d-5e7a9c1b3d26",
      "title": "Contoso Retail — expansion",
      "value": 36000,
      "currency": "EUR",
      "probability": 40,
      "expected_close_date": "2026-12-19",
      "forecast_category": "pipeline",
      "stage": "Qualification",
      "company_name": null
    }
  ]
}

Which deals count

  • Open deals only: deals that are won or lost are left out.
  • Their expected_close_date falls between period_start and period_end, both inclusive.
  • Deals in the omit category are left out; deals without a category count as pipeline. A deal’s category is one of commit, best_case, pipeline, omit — see forecast categories.
  • owner_id and pipeline_id narrow it to one person’s or one pipeline’s deals.

Retrieve the forecast

GET/api/v1/analytics/forecast

Requires analytics:read (deals:read is accepted too).

Returns the forecast for a period. Without the Analytics hub in the plan it answers 403 hub_not_in_plan.

Query parameters

Returns

The forecast object.

GET/api/v1/analytics/forecast
curl -G https://acme.nextora.co/api/v1/analytics/forecast \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -d period_start=2026-10-01 \
  -d period_end=2026-12-31 \
  -d pipeline_id=9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34
Response200 OK
{
  "data": {
    "period": {
      "start": "2026-10-01",
      "end": "2026-12-31"
    },
    "categories": [
      {
        "category": "commit",
        "deal_count": 2,
        "total_value": 27000,
        "weighted_value": 23400,
        "avg_probability": 85
      },
      {
        "category": "best_case",
        "deal_count": 1,
        "total_value": 24000,
        "weighted_value": 14400,
        "avg_probability": 60
      },
      {
        "category": "pipeline",
        "deal_count": 1,
        "total_value": 36000,
        "weighted_value": 14400,
        "avg_probability": 40
      }
    ],
    "totals": {
      "commit": 27000,
      "best_case": 51000,
      "weighted": 52200,
      "pipeline": 87000,
      "deal_count": 4
    },
    "deals": [
      {
        "id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
        "title": "Northwind Analytics — annual plan",
        "value": 24000,
        "currency": "EUR",
        "probability": 60,
        "expected_close_date": "2026-11-27",
        "forecast_category": "best_case",
        "stage": "Proposal",
        "company_name": "Northwind Analytics"
      },
      {
        "id": "3b5d7f9a-1c3e-4a5c-8e7f-9a1b3c5d7e02",
        "title": "Harbor Logistics — pilot",
        "value": 9000,
        "currency": "EUR",
        "probability": 80,
        "expected_close_date": "2026-10-31",
        "forecast_category": "commit",
        "stage": "Negotiation",
        "company_name": "Harbor Logistics"
      },
      {
        "id": "5d7f9b1c-3e5a-4c7e-9a1b-3c5e7a9b1d14",
        "title": "Fabrikam — renewal",
        "value": 18000,
        "currency": "EUR",
        "probability": 90,
        "expected_close_date": "2026-12-15",
        "forecast_category": "commit",
        "stage": "Negotiation",
        "company_name": "Fabrikam"
      },
      {
        "id": "7f9b1d3e-5a7c-4e9a-8b1d-5e7a9c1b3d26",
        "title": "Contoso Retail — expansion",
        "value": 36000,
        "currency": "EUR",
        "probability": 40,
        "expected_close_date": "2026-12-19",
        "forecast_category": "pipeline",
        "stage": "Qualification",
        "company_name": null
      }
    ]
  }
}