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. |