asset_get

Fetch one Asset with its Registrations, and the state of each one. The agent polls a running Registration with this tool.

Ask whether a file is ready for an advertiser. The agent reads the Asset and each of its Registrations, and tells you the state of each one.

“Is the spring sale video ready in the Acme account yet?”

The agent finds the Asset, reads it with this tool, and finds the Registration with that advertiser. You get one of three answers: the file is ready, the provider still processes it, or the Registration failed, with the reason. A video can take several minutes at the provider. The agent can ask again until the Registration settles.

This tool is part of the job Bring your own creative.

Reference

Fetch one Asset together with its Registrations — where it has been placed, and how each placement went.

This is also how you poll a registration you started: a running Registration is still in progress. Video can stay running for several minutes while the provider processes it, which is normal.

Input

Argument	Type	Required	Description
`asset_id`	string	yes	The Asset id (ast_…).

Output

A successful call returns this object in structuredContent.

Field	Type	Always present	Description
`asset`	object	yes	The Asset, with its Registrations: one for each advertiser, with its state.
`asset.contentHash`	string	yes	AdCrunch’s own hash of the stored bytes. A hint for de-duplication, never an identity, and never a provider’s hash. Empty when the store reports none.
`asset.createdAt`	number	yes	Milliseconds since the Unix epoch, UTC.
`asset.createdBy`	string	yes	The user who reserved the upload.
`asset.deletedAt`	number or null	yes	Always `null` here. A deleted Asset is not answered.
`asset.durationMs`	number or null	yes	How long the video runs, in milliseconds, read from the header of the file at finalize. `null` for an image. For a video, `null` when the file does not state it, or for an Asset uploaded before AdCrunch read it.
`asset.filename`	string	yes	The name the file was uploaded under. Never a lookup key.
`asset.height`	number or null	yes	The height in pixels as the file is displayed, with its rotation applied, read from the header of the file at finalize. `null` when the file does not state it, or for an Asset uploaded before AdCrunch read it.
`asset.id`	string	yes	The id of the Asset, `ast_…`.
`asset.key`	string	yes	Where the bytes are held. Read-only, and never sent by you.
`asset.kind`	one of `image`, `video`	yes	Follows from `mimeType`, so the stored bytes verify it at finalize. It selects how a provider takes the file.
`asset.mimeType`	string	yes	The `Content-Type` the file was uploaded with, verified against the stored bytes at finalize.
`asset.name`	string or null	yes	The name a person gave this Asset, and what a provider receives at a future registration. `null` until somebody renames it, and the filename is the fallback.
`asset.organizationId`	string	yes	The organization that owns the Asset.
`asset.sizeBytes`	number	yes	Read from the stored object at finalize.
`asset.status`	one of `pending`, `ready`	yes	`ready` once the bytes have been inspected. A `pending` Asset is a reservation whose bytes have not arrived, and no operation here answers one.
`asset.updatedAt`	number or null	yes	When the Asset last changed, in milliseconds since the Unix epoch, UTC: at finalize, or at the last rename.
`asset.width`	number or null	yes	The width in pixels as the file is displayed, with its rotation applied, read from the header of the file at finalize. `null` when the file does not state it, or for an Asset uploaded before AdCrunch read it.
`asset.registrations`	array of object	yes	Each Registration of this Asset, one for each advertiser, with its state. An empty array means that the Asset has no Registration.
`asset.registrations[].advertiserId`	string	yes	The advertiser whose provider library gets the Asset.
`asset.registrations[].assetId`	string	yes	The Asset that the Registration places.
`asset.registrations[].createdAt`	number	yes	Milliseconds since the Unix epoch, UTC.
`asset.registrations[].deletedAt`	number or null	yes	Always `null` here. When a retry replaces a failed Registration, AdCrunch sets this time on the old one and answers it no more.
`asset.registrations[].failureReason`	string or null	yes	Why the Registration failed, as a sentence: the words of the provider, or the words of AdCrunch. `null` unless `status` is `failed`.
`asset.registrations[].id`	string	yes	The id of the Registration, `reg_…`.
`asset.registrations[].organizationId`	string	yes	The organization that owns the Asset.
`asset.registrations[].provider`	one of `meta`, `gads`, `tiktok`, `x`, `openai`, `snapchat`, `dv360`	yes	The provider that owns the advertiser.
`asset.registrations[].providerIdentifier`	string or null	yes	The id that the provider gave the file: a Meta image hash, or the id of the image or the video at the provider. `null` until the provider gives it, and `null` on a `failed` Registration. An image gets its id when the Registration becomes `ready`. A video gets its id earlier, while the Registration is `running`, because the provider gives the id before it has processed the file. Build a creative from a `ready` Registration only.
`asset.registrations[].status`	one of `running`, `ready`, `failed`	yes	Video can stay `running` for several minutes while the provider processes it. That is normal, and not a failure.
`asset.registrations[].updatedAt`	number or null	yes	When the Registration last changed, in milliseconds since the Unix epoch, UTC. `null` until its first change.
`asset.registrations[].uploadSessionId`	string or null	yes	An in-flight provider upload session, where the protocol has one. `null` for every image.
`asset.registrations[].workflowId`	string	yes	The durable execution that runs the Registration.

Failure codes

A failed call has isError set, and structuredContent.error holds one of these codes. Errors describes the shape of a failed call.

not_found
forbidden
invalid_request
internal_error

Scope

The token must hold asset:read. Auth & scopes lists each scope.

Annotations

A client reads these hints. A hint that the tool does not declare has the default value of the MCP specification.

Read-only. The tool changes nothing.
Closed world. The tool reads and writes the data of AdCrunch only.

Example

The arguments:

{
  "asset_id": "ast_7c1e9a"
}

The result, in structuredContent:

{
  "asset": {
    "contentHash": "9d2f41b7c6e8a35014f7b2d9c3e6a810",
    "createdAt": 1790000000000,
    "createdBy": "usr_2e5b84",
    "deletedAt": null,
    "durationMs": 15000,
    "filename": "spring-sale.mp4",
    "height": 1920,
    "id": "ast_7c1e9a",
    "key": "org_3a7f10/ast_7c1e9a",
    "kind": "video",
    "mimeType": "video/mp4",
    "name": "Spring sale 9:16",
    "organizationId": "org_3a7f10",
    "sizeBytes": 24117248,
    "status": "ready",
    "updatedAt": 1790000120000,
    "width": 1080,
    "registrations": [
      {
        "advertiserId": "acc_1203456789012345",
        "assetId": "ast_7c1e9a",
        "createdAt": 1790000121000,
        "deletedAt": null,
        "failureReason": null,
        "id": "reg_4b81d2",
        "organizationId": "org_3a7f10",
        "provider": "meta",
        "providerIdentifier": "23843178520310445",
        "status": "ready",
        "updatedAt": 1790000249000,
        "uploadSessionId": "1264871528937461",
        "workflowId": "reg_4b81d2"
      }
    ]
  }
}