Skip to content
AdCrunch
Esc
↑↓navigate↵open⌘Jpreview

Get a Line Item

Reads one Line Item with its readiness: whether AdCrunch can build it now, and if not, why. Ask this before any provider call.

This is the one read that carries the readiness. The list of Line Items and the writes of a Line Item return the Line Item without it. The read of a Campaign Plan returns no Line Item. This call reads. It changes nothing, and it calls no provider. It answers for every channel, including a channel AdCrunch cannot write to.

The answer is the Line Item, with the same fields as a row of the list of the Line Items of its Campaign Plan, and two more fields: currency and readiness. currency is the currency of the Campaign Plan. Each amount of the Line Item is in whole units of that currency. status is the status of the Line Item. readiness.status is the verdict.

A Line Item is not ready in these conditions:

  • A person has not validated the Line Item in the AdCrunch console. The validation is a record: the provider write tools do not check it.
  • AdCrunch cannot write to the channel. The answer names the provider that sells it, or null when nobody we integrate with sells it.
  • The Line Item has no ad account.
  • The ad account is not connected to this organization.
  • The ad account belongs to a different provider than the channel.
  • The currency of the ad account is different from the Campaign Plan currency, or AdCrunch does not know that currency yet. To make it known, refresh the provider connection.
  • The Line Item and the Campaign Plan give no date at all.
  • The resolved start follows the resolved end. Each row is ordered on its own, and only the pair shows this.

AdCrunch never converts a currency. A converted budget is a different plan.

The verdict is advice. The provider write tools do not read it.

When the Line Item is ready, the verdict also gives the dates that apply, and it tells you whether the budget goes to the provider as a lifetime total or as a daily rate.

The MCP tool line_item_get gives the same answer to an agent.

GET/context/campaign-plans/{slug}/line-items/{lineItemId}
Authorization
AuthorizationBearer token · headerrequired

Send Authorization: Bearer <credential>.

Use an API key (acr_…), from the AdCrunch console under Settings → API keys.

The credential names the organization, and no operation takes an organization parameter.

See https://docs.adcrunch.dev/api/authentication.

Path parameters
lineItemIdstringrequired
matches ^lni_[\s\S]{0,}$
slugstringrequired
Responses
200

The Line Item, its readiness and the currency of its Campaign Plan. Every readiness outcome is a 200, ready included. The example shows ready; the schema lists the nine refusals and what each one carries.

advertiserIdstring | nullrequired
ageMaxnumber | nullrequired
ageMinnumber | nullrequired

Each bound is independently optional, so "35+" is expressible.

budgetnumber | nullrequired

Whole units of the plan’s currency.

campaignPlanIdstringrequired
channelstringrequired

The planner’s word for what is being bought, not a provider name. A plan may name a channel we cannot execute.

Allowed:metatiktoksnapchatgoogle_searchgoogle_pmaxgoogle_displayyoutubeprogrammatic_displaylinkedinx
countriesstring[]required
createdAtnumberrequired

Milliseconds since the Unix epoch, UTC.

createdBystringrequired
effectiveEndDatestring | nullrequired

The line’s own bound where it has one, else the plan’s.

effectiveStartDatestring | nullrequired

A calendar date, YYYY-MM-DD.

endDatestring | nullrequired

A calendar date, YYYY-MM-DD.

executablebooleanrequired

Whether this channel could be executed at all today. Derived from our capabilities, never a promise that it will be.

executionsobject[]required

What this line has spawned. Never a claim that it is finished — nobody declared how many objects a line should produce.

Show properties
Array of object
advertiserIdstringrequired
createdAtnumberrequired

Milliseconds since the Unix epoch, UTC.

entityIdstringrequired

The provider’s own id, unprefixed, so it joins to entities.

entityTypestringrequired

The provider’s word for the level — campaign, adset, ad.

idstringrequired
mutationIdstring | nullrequired

The id of the Mutation that performed the write, when known.

providerstringrequired
genderstring | nullrequired
Allowed:allmenwomen
idstringrequired
namestring | nullrequired

A short label of the Line Item, at most 60 characters after trimming. It is not unique, and it is not a handle: nothing looks a Line Item up by it. A blank name is no name. null for no name.

objectivestringrequired
Allowed:awarenessengagementleadssalestrafficapp_promotion
personaIdstring | nullrequired

Explains the targeting; never supplies its values.

providerstring | nullrequired

Who sells this channel, or null when nobody we integrate with does.

revisionnumberrequired

Increments on every write. Send it back as base_revision to edit; a stale one answers 409.

startDatestring | nullrequired

A calendar date, YYYY-MM-DD.

statusstringrequired

validated when a person validated the Line Item. It is a record, not a gate: the provider write tools do not check it. The readiness reads it.

Allowed:draftvalidated
targetMetricstring | nullrequired

The metric of the target, or null for no target. cpa, cpc and cpm are costs: lower is better. roas is a return: higher is better. A target blocks nothing: approval and the readiness do not read it.

Allowed:cpacpccpmroas
targetValuenumber | nullrequired

The value of the target: whole units of the plan’s currency for cpa, cpc and cpm, a ratio for roas. null for no target.

unitstringrequired

How budget reads, derived from the effective end date. Present → a total for the period; absent → a daily rate. A surface must print this beside the amount.

Allowed:totaldaily
updatedAtnumber | nullrequired

Milliseconds since the Unix epoch, UTC.

currencystringrequired

The currency of the Campaign Plan (ISO 4217). Each amount of the Line Item is in whole units of it.

readinessobjectrequired

Whether AdCrunch can build the Line Item now, and if not, the first reason. The verdict is discriminated on status. AdCrunch derives it on each read and never stores it. It is advice: the provider write tools do not read it.

Show properties
One of:
object
advertiserIdstringrequired
budgetnumber | nullrequired
currencystringrequired

The plan’s currency, confirmed equal to the account’s.

endDatestring | nullrequired

A calendar date, YYYY-MM-DD.

providerstringrequired
startDatestring | nullrequired

A calendar date, YYYY-MM-DD.

statusstringrequired
Allowed:ready
unitstringrequired
Allowed:totaldaily
object
statusstringrequired

A person has not validated the Line Item in the AdCrunch console. The validation is a record: the provider write tools do not check it.

Allowed:not_validated
object
channelstringrequired
Allowed:metatiktoksnapchatgoogle_searchgoogle_pmaxgoogle_displayyoutubeprogrammatic_displaylinkedinx
providerstring | nullrequired

Who sells it, when someone does but we cannot write there yet.

statusstringrequired
Allowed:channel_not_executable
object
statusstringrequired
Allowed:no_advertiser
object
statusstringrequired
Allowed:advertiser_not_owned
object
actualstringrequired
expectedstringrequired
statusstringrequired
Allowed:provider_mismatch
object
advertiserIdstringrequired
statusstringrequired

Refresh the provider connection.

Allowed:account_currency_unknown
object
accountCurrencystringrequired
planCurrencystringrequired
statusstringrequired

Never converted. A converted budget is a different plan, and the planner allocated what they allocated.

Allowed:currency_mismatch
object
statusstringrequired
Allowed:no_window
object
endDatestringrequired

A calendar date, YYYY-MM-DD.

startDatestringrequired

A calendar date, YYYY-MM-DD.

statusstringrequired
Allowed:window_inverted
400

The request does not match the schema of this operation: a field is missing or has the wrong type, or the body is not valid JSON. error is invalid_request, and issues names each field. Nothing was changed.

issuesobject[]required

One entry for each field that does not match.

Show properties
Array of object
instringrequired

The part of the request that holds the field.

Allowed:bodycookieheadersparamsquery
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

pathstringrequired

A JSON Pointer into that part of the request, such as /filename. An empty string is the whole part.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:invalid_request
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

401

No API key, or one that does not resolve. See the security scheme. error is unauthorized.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:unauthorized
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

402

The organization has no active subscription. An owner subscribes at paywallUrl. error is organization_unentitled.

paywallUrlstring<uri>required

The page where an owner of the organization subscribes. Show it to the person.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:organization_unentitled
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

403

The caller does not hold campaign_plan:read. error is forbidden.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:forbidden
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

404

No such Campaign Plan, or no Line Item with that id on it. error is not_found.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

Request
curl -X GET 'https://api.adcrunch.dev/context/campaign-plans/string/line-items/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'
Response
{
  "advertiserId": "acc_1203456789012345",
  "ageMax": 44,
  "ageMin": 25,
  "budget": 2500,
  "campaignPlanId": "cpl_4e1a08",
  "channel": "meta",
  "countries": [
    "FR",
    "BE"
  ],
  "createdAt": 1768435200000,
  "createdBy": "usr_5d2b71",
  "effectiveEndDate": "2026-05-31",
  "effectiveStartDate": "2026-03-01",
  "endDate": null,
  "executable": true,
  "executions": [],
  "gender": "all",
  "id": "lni_2d9e77",
  "name": "Spring reach, France and Belgium",
  "objective": "sales",
  "personaId": "psn_8c4a20",
  "provider": "meta",
  "revision": 2,
  "startDate": null,
  "status": "validated",
  "targetMetric": "cpa",
  "targetValue": 24.5,
  "unit": "total",
  "updatedAt": 1769040000000,
  "currency": "EUR",
  "readiness": {
    "advertiserId": "acc_1203456789012345",
    "budget": 2500,
    "currency": "EUR",
    "endDate": "2026-05-31",
    "provider": "meta",
    "startDate": "2026-03-01",
    "status": "ready",
    "unit": "total"
  }
}