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.

# 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"
    }
  }
}'
// 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);
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).
{
  "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), 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.