---
title: Read a batch idea by idea
url: /docs/developers/reference/social-batch-read
---

# Read a batch idea by idea

`social.batch.read@1`

Read one Generate run back, idea by idea: each idea's number, name and recipe, the answers it was started with once the run has ended, each account's saved draft, and whether a picture may already have been charged. Requires **Read social**, current edition access and the exact run-inspector binding on the same key. Nothing is written, spent or started, and no caption, picture or amount is returned.

## Read a batch that ended with one idea not saved

Use the root run Generate returned. The answers are only given once the run has ended. A run that is not your business's Generate batch, or that you may not inspect, is refused as no batch.

```curl tabs
# A new operationId for each new request; the same one to retry it.
curl https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations \
  -H "Authorization: Bearer gl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "featureId": "YOUR_FEATURE_ID",
    "export": "readBatch",
    "contractRef": "social.batch.read@1"
  },
  "operationId": "batch-read-1",
  "input": {
    "source": {
      "featureId": "juniper-cakes.automations",
      "runRef": "YOUR_ROOT_RUN_REFERENCE"
    }
  }
}'
```

```javascript tabs
// A new operationId for each new request; the same one to retry it.
const response = await fetch(
  "https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer gl_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "target": {
        "featureId": "YOUR_FEATURE_ID",
        "export": "readBatch",
        "contractRef": "social.batch.read@1"
      },
      "operationId": "batch-read-1",
      "input": {
        "source": {
          "featureId": "juniper-cakes.automations",
          "runRef": "YOUR_ROOT_RUN_REFERENCE"
        }
      }
    }),
  },
);
const receipt = await response.json();
console.log(response.status, receipt);
```

```python tabs
import requests

# A new operationId for each new request; the same one to retry it.
response = requests.post(
    "https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
    headers={"Authorization": "Bearer gl_YOUR_API_KEY"},
    json={
        "target": {
            "featureId": "YOUR_FEATURE_ID",
            "export": "readBatch",
            "contractRef": "social.batch.read@1",
        },
        "operationId": "batch-read-1",
        "input": {
            "source": {
                "featureId": "juniper-cakes.automations",
                "runRef": "YOUR_ROOT_RUN_REFERENCE",
            },
        },
    },
    timeout=30,
)
print(response.status_code, response.json())
```

## Parameters

What goes in `input`:

| Name | Type | Required | Description |
|---|---|---|---|
| `source` | object | Yes | The root run Generate returned and its Automations feature. |
| `source.featureId` | string | Yes | The Automations feature that owns the run, not the Social feature. |
| `source.runRef` | string | Yes | The opaque root run reference. A recipe's child run is not a batch. |

## Response

A call that worked answers `200` with an `applied` receipt; its `output` holds these fields. `GET /catalog/social.batch.read@1` answers the complete shape as JSON Schema.

| Name | Type | Description |
|---|---|---|
| `runRef` | string | The root run read. |
| `state` | one of `preparing`, `queued`, `running`, `waiting`, `needs-input`, `suspended`, `succeeded`, `completed-with-errors`, `failed`, `uncertain`, `cancelled` | The run's state now. |
| `ideas` | array of object | Every idea the run was started with, in the order asked. |
| `ideas[].key` | string | The idea's key. |
| `ideas[].number` | integer | The idea's position in the request it was first asked in; a retry keeps it. |
| `ideas[].name` | string | What the idea is called: the first line of its own brief, else the shared brief, else the recipe's title. |
| `ideas[].recipe` | object | The recipe it was made with. |
| `ideas[].recipe.presetRef` | string | The recipe as asked, with its version. |
| `ideas[].recipe.title` | string | The recipe's title when the batch started. |
| `ideas[].paid` | boolean | Whether the recipe buys an AI picture. |
| `ideas[].answers` | array or null | The answers the idea was started with, in the recipe's question order; `null` while the run has not ended. Each answer has `label` (the question), `role` (what it is for, such as `brief`, or null) and `value` (words, or for a picture the Drive file chosen). |
| `ideas[].accounts` | array of object | The idea's outcome for each account: from the run's result when it has one, else only the accounts with a saved draft. |
| `ideas[].accounts[].accountRef` | object | The account. |
| `ideas[].accounts[].accountRef.businessProfileId` | string | The business that owns the account. |
| `ideas[].accounts[].accountRef.featureId` | string | The account's Data feature. |
| `ideas[].accounts[].accountRef.collectionId` | string | The accounts table. |
| `ideas[].accounts[].accountRef.id` | string | The account row id. |
| `ideas[].accounts[].status` | one of `pending`, `saved`, `not-saved`, `cancelled`, `skipped` | What happened: `saved`, `not-saved`, `skipped`, `cancelled` or `pending`. |
| `ideas[].accounts[].editionRef` | object or null | The saved draft to open, or `null` when there is none, it was deleted or you may not read it. It is a row reference with `businessProfileId`, `featureId`, `collectionId` and `id`. |
| `ideas[].accounts[].reason` | object or null | Why nothing was saved, from the run's result; `null` otherwise. It has `code` (the failure code) and `message` (the plain reason). |
| `ideas[].pictureStarted` | boolean or null | `true` once this idea's picture was handed to the picture service, so a charge may have been made; `false` when it was not; `null` when the idea buys no picture or the pictures were not asked for by you. |
| `pictures` | object or null | How far the one yes for pictures got, or `null` when you asked for none for this run. It has `covered` (how many pictures the yes covered) and `started` (how many were handed to the picture service). |
| `retryOf` | object or null | The earlier run whose ideas this run repeats, or `null`. It has `runRef` (that earlier run) and `ideaKeys` (the ideas of it that were repeated). |

```json title="Response"
{
  "status": "applied",
  "operationId": "batch-read-1",
  "output": {
    "runRef": "YOUR_ROOT_RUN_REFERENCE",
    "state": "completed-with-errors",
    "ideas": [
      {
        "key": "spring",
        "number": 1,
        "name": "Announce our new spring flavours",
        "recipe": {
          "presetRef": "YOUR_RECIPE_REF",
          "title": "A post from a brief"
        },
        "paid": false,
        "answers": [
          {
            "label": "What should this post be about?",
            "role": "brief",
            "value": "Announce our new spring flavours"
          }
        ],
        "accounts": [
          {
            "accountRef": {
              "businessProfileId": "YOUR_BUSINESS_ID",
              "featureId": "juniper-cakes.data",
              "collectionId": "juniper-cakes.social-accounts",
              "id": "YOUR_ACCOUNT_ID"
            },
            "status": "not-saved",
            "editionRef": null,
            "reason": {
              "code": "AUTOMATION.AGENT_FAILED",
              "message": "The writer could not write this post."
            }
          }
        ],
        "pictureStarted": null
      }
    ],
    "pictures": null,
    "retryOf": null
  }
}
```

## Errors

It reads and changes nothing. Besides the answers every request can get ([Errors](../errors.md)), its receipt can say:

| Status | HTTP | What it means |
|---|---|---|
| `rejected` | 400, or 403 when it's a matter of access | Not done. `diagnostics` says why: each has a `code`, a `path` into what you sent and a `message`. |

The codes in `diagnostics` you're most likely to see:

| Code | Status | What it means |
|---|---|---|
| `SOCIAL.BATCH_NOT_FOUND` | `rejected` | The run is unknown, foreign, not one you may inspect, or not a Generate batch. |
| `SOCIAL.POLICY_DENIED` | `rejected` | Current policy does not permit reading posts. |
