From 1a7b44e4e55f2c21c95cab30b50309daa2baba8d Mon Sep 17 00:00:00 2001
From: crprashant <5108573+crprashant@users.noreply.github.com>
Date: Wed, 24 Jun 2026 12:14:32 -0700
Subject: [PATCH] docs: clarify df.status()/df.result() take instance_id, not
 label (#167)

State explicitly that df.status() and df.result() accept an instance_id from df.start(), not a label, and document the supported label -> instance_id resolution pattern via df.list_instances(). Also fix the df.status() example casing to the actual lowercase status values.

Closes #167
---
 USER_GUIDE.md         | 19 ++++++++++++++++---
 docs/api-reference.md | 15 +++++++++++++--
 2 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/USER_GUIDE.md b/USER_GUIDE.md
index 7fca2eca..fce8fadb 100644
--- a/USER_GUIDE.md
+++ b/USER_GUIDE.md
@@ -183,8 +183,8 @@ df.sql('SELECT 1') ~> df.sql('SELECT 2')
 | `df.break(value)` | Exit loop with **literal** return value (not auto-wrapped as SQL) | `df.break('{"done": true}')` |
 | `df.start(func, label, database)` | Start function (optionally in another database) | `df.start('SELECT 1', 'job')` |
 | `df.cancel(id, reason)` | Cancel function | `df.cancel('a1b2c3d4', 'Done')` |
-| `df.status(id)` | Get status | `df.status('a1b2c3d4')` |
-| `df.result(id)` | Get result | `df.result('a1b2c3d4')` |
+| `df.status(id)` | Get status by instance_id (not label) | `df.status('a1b2c3d4')` |
+| `df.result(id)` | Get result by instance_id (not label) | `df.result('a1b2c3d4')` |
 | `df.explain(input)` | Visualize graph | `df.explain('a1b2c3d4')` |
 | `df.setvar(name, value)` | Set durable function variable | `df.setvar('api_url', 'https://...')` |
 | `df.getvar(name)` | Get durable function variable | `df.getvar('api_url')` |
@@ -1484,14 +1484,27 @@ SELECT * FROM df.metrics();
 
 ### Quick Status Check
 
+`df.status()` and `df.result()` take an **`instance_id`** (returned by `df.start()`), **not** a label. Passing a label returns `NULL`.
+
 ```sql
--- Status only
+-- Status only (lowercase: 'pending', 'running', 'completed', 'failed', 'cancelled')
 SELECT df.status('a1b2c3d4');
 
 -- Result only
 SELECT df.result('a1b2c3d4');
 ```
 
+If you started the run with a label, resolve the label to an `instance_id` first:
+
+```sql
+-- Status for a labeled run
+SELECT df.status(instance_id)
+FROM df.list_instances()
+WHERE label = 'my-job';
+```
+
+If you reuse a label across runs, multiple instances can match — pass the specific `instance_id` you want.
+
 ### Worker Liveness
 
 Check whether the background worker is alive and healthy:
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 05fb16ab..ecc03cb4 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -316,14 +316,25 @@ df.cancel('a1b2c3d4', 'Manual stop')
 
 Gets instance status.
 
+> **Note:** the argument is an **`instance_id`** (returned by `df.start()`), **not** a label. Passing a label returns `NULL`, since no instance has that ID. To check a labeled run, resolve the label to an `instance_id` first (see example below).
+
 | Parameter | Type | Auto-wrap | Description |
 |-----------|------|-----------|-------------|
-| `instance_id` | TEXT | ❌ Literal | Target instance ID |
+| `instance_id` | TEXT | ❌ Literal | Target instance ID from `df.start()` (not a label) |
 
 ```sql
-SELECT df.status('a1b2c3d4');  -- Returns: 'Running', 'Completed', etc.
+-- By instance_id. Returns a lowercase status:
+-- 'pending', 'running', 'completed', 'failed', or 'cancelled'.
+SELECT df.status('a1b2c3d4');
+
+-- Have a label instead of an instance_id? Resolve it first:
+SELECT df.status(instance_id)
+FROM df.list_instances()
+WHERE label = 'my-job';
 ```
 
+If you reuse a label across runs, multiple instances can match — pass the specific `instance_id` you want.
+
 ---
 
 ### df.result(instance_id)