# Request (Timeseries)

## Method

API is using **POST** method

Supports:\
✅ **Time Series Forecasting** (predicting numeric values over a date range)

## Request URL

```
https://app.graphite-note.com/api/v1/prediction/model/[model-code]
```

Replace `[model-code]` with your model’s code.\
Find it in the model’s **Settings → ID** section.

## Headers

* **Authorization:** `Bearer [token]`\
  (Get your token in **Account Info** inside the app.)
* **Content-Type:** `application/json`

## Body

The v1 time-series API expects a structured object at `data.predict_values`:

Required fields

* `startDate` (string, `YYYY-MM-DD`)
* `endDate` (string, `YYYY-MM-DD`)
* `sequenceID` (string; use `"n/a"` if not applicable)

Conditional field

* `daysData` (array) — **only** when the model was trained **with regressors**.\
  One object per date with:
  * `date` (string, `YYYY-MM-DD`)
  * All regressor columns used in training (e.g., `promotion`, `price`, `weather`, …)

> If the model used regressors, you must supply **every regressor for every date** in the requested range via `daysData`.

***

### Example A — Without regressors

```bash
curl -L -X POST 'https://app.graphite-note.com/api/v1/prediction/model/[model-code]' \
  -H 'Authorization: Bearer [token]' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "predict_values": {
        "startDate": "2025-10-01",
        "endDate":   "2025-12-01",
        "sequenceID": "Store001"
      }
    }
  }'
```

**Typical response**

```json
{
  "data": [
    {
      "date": "2025-10-01T00:00:00.000",
      "predicted": 1225707.2645253073,
      "predicted_lower": 1190271.3575973918,
      "predicted_upper": 1257483.2005986127
    },
    {
      "date": "2025-11-01T00:00:00.000",
      "predicted": 1354638.5614777768,
      "predicted_lower": 1322609.8547555234,
      "predicted_upper": 1388121.5808224094
    },
    {
      "date": "2025-12-01T00:00:00.000",
      "predicted": 1882129.6128404615,
      "predicted_lower": 1847289.9345675157,
      "predicted_upper": 1913548.0087476152
    },
    {
      "sequenceID": "Store001"
    }
  ]
}
```

***

### Example B — With regressors (`daysData` required)

```bash
curl -L -X POST 'https://app.graphite-note.com/api/v1/prediction/model/[model-code]' \
  -H 'Authorization: Bearer [token]' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "predict_values": {
        "startDate": "2025-09-22",
        "endDate":   "2025-09-29",
        "sequenceID": "Alpha",
        "daysData": [
          { "date": "2025-09-22", "promotion": "A" },
          { "date": "2025-09-29", "promotion": "B" }
        ]
      }
    }
  }'
```

**Typical response**

```json
{
  "data": [
    {
      "date": "2025-09-22T00:00:00.000",
      "predicted": 2370.4695876452001,
      "predicted_lower": 2279.2000645561998,
      "predicted_upper": 2458.3810902849
    },
    {
      "date": "2025-09-29T00:00:00.000",
      "predicted": 2694.2617946204,
      "predicted_lower": 2604.5116258851999,
      "predicted_upper": 2788.9465525872001
    },
    {
      "sequenceID": "Alpha"
    }
  ]
}
```

***

## Parameter Reference

| Field         | Type   | Required    | Description                                                                               |
| ------------- | ------ | ----------- | ----------------------------------------------------------------------------------------- |
| `startDate`   | string | Yes         | Start of prediction window (`YYYY-MM-DD`). Must align to model frequency.                 |
| `endDate`     | string | Yes         | End of prediction window (`YYYY-MM-DD`). Inclusive for requested outputs.                 |
| `sequenceID`  | string | Yes         | Sequence identifier. Use `"n/a"` if not used by your workflow.                            |
| `daysData`    | array  | Conditional | Only for models trained **with regressors**. One row per date.                            |
| `date`        | string | Conditional | Inside `daysData`. Date the regressor values apply to (`YYYY-MM-DD`).                     |
| `<regressor>` | any    | Conditional | Inside `daysData`. Every regressor column used in training must be present for each date. |

**Response fields**

* `date`: ISO datetime string (`YYYY-MM-DDT00:00:00.000`) aligned to the model frequency.
* `predicted`: point forecast.
* `predicted_lower`, `predicted_upper`: uncertainty bounds.
* A trailing object with `{ "sequenceID": "…" }` echoes your request identifier.

***

## Validation Rules & Tips

* **Dates:** Use `YYYY-MM-DD`. Ensure the range matches model frequency (daily, weekly, monthly).
* **Regressors:** For regressor-trained models, provide **all regressors** for **every date** in `daysData`. Missing any will prevent forward predictions.
* **Types:** Match training schema. Numeric vs categorical must align with what the model expects.
* **Range size:** Extremely large ranges may be throttled. Test with a small window first.
* **Echoed sequence:** The API echoes your `sequenceID` at the end of the response array to help correlate requests.

***