Uploads

Send a POI or cohort file to Intuizi. Conventions apply to every command here.

Uploading is three steps. Reserve a slot, which returns a presigned URL and a reference. PUT the bytes to that URL. Then pass the reference to a cohort or POI submission create. uploads put runs the first two and prints the reference, and the create is a separate command. uploads reserve runs only the first, for a caller that wants to do its own PUT.

A reference can only be claimed by the create that matches its --purpose: cohorts create --upload-reference for a cohort upload, and poi submissions create --upload-reference for a poi_submission upload. It is single-use: once a create has used it, it cannot be used again. A cohort create refused by the build budget or the data-scan limit, a file over the purpose’s size cap, and a POI file that fails validation all use the reference up, so upload the file again for a new one before retrying.

A create that fails with No file has been uploaded for this reference yet. leaves the reference usable until expires_at. The message has two causes. If the PUT had not finished, finish it and run the create again. If the file is a POI file with only a header row and no data rows, running the create again gets the same error every time: add the rows and upload the file again for a new reference. uploads put prints a reference only after its PUT has succeeded, so for a reference it printed, the cause is always the second one. A cohort create that fails with Error occurred, please try again. also leaves the reference usable, so run the create again. cohorts preview --upload-reference reads a cohort upload without claiming it.

A build-budget refusal of cohorts create --upload-reference is not retried, because the refused attempt has already used the reference. The CLI prints the 429 as it came, ending with its Retry-After (for example (429, Retry-After: 1800s)), and adds that the file has to be uploaded again for a new reference. Check intuizi usage --json | jq .data.build_budget and upload the file again once the budget has room. intuizi usage requires additional permissions which need to be approved by your Account Manager (see Usage).

A reference also has to be claimed before the reservation’s expires_at, the presigned URL expiry on Limits & Quotas. The clock starts at the reservation, so the upload time of a large file counts against it. A create after expires_at is rejected even when the PUT succeeded, and the file has to be uploaded again for a new reference. cohorts preview does not check the deadline, so a preview that works does not mean the reference can still be claimed. uploads put prints only the reference, so run the create soon after it, or read expires_at from --json. It is written as YYYY-MM-DD HH:MM:SS in server time with no offset, so rather than compare it with your local clock, count the window from the reservation.

Put

Upload a file and print the reference a create command consumes. See Create an Upload.

The file is the command’s argument, and its name and size go into the reservation. So a poi_submission file’s name must end in .csv or .txt, and the name of a cohort file decides whether it imports as one file or as a folder (see Cohorts). The accepted --purpose values are on Create an Upload.

The reference is the only thing printed on stdout, so it can be captured and passed to the create:

ref=$(intuizi uploads put customers.csv --purpose cohort)
intuizi cohorts create --name "Q3 customers" --upload-reference "$ref" \
  --file-format csv --identifier-type hem_sha256 \
  --identifier-column email_sha256

With --json, put prints the reservation envelope instead, once the PUT has succeeded, so .data[0].upload_reference is the same value.

Reserve

Reserve a slot and print its presigned URL without transferring anything, for a caller that wants to do its own PUT. See Create an Upload.

PUT the file to upload_url with the headers the reservation returned, then claim the reference with a create, both before expires_at. The table shows headers as {...}, so a script reads upload_url, headers, and upload_reference from --json:

intuizi uploads reserve --purpose cohort --filename customers.csv \
  --content-length 1048576 --json

The purpose’s size cap applies to --content-length here, and again to the bytes actually uploaded when a create claims the reference.