API reference

FOCUS

Export your invoices as a FOCUS dataset, and read your providers' FOCUS billing data.

More about this resource

FOCUS is the FinOps Foundation's open format for billing data. Pleaxy works with it in both directions. An export writes the workspace's invoices, debit notes and accepted credit notes as a FOCUS Cost and Usage dataset, for a FinOps or reporting tool. A FOCUS source reads billing data in that format, from files you upload or from a provider's own FOCUS export, and stores each month's totals by invoice, issuer and cost center. Export and import are switched on per workspace; while one is off, its endpoints answer 404.

List FOCUS exports

Lists the FOCUS exports of the last 7 days, and whether export is on.

GET/v1/workspaces/{regionId}/focus-exports

Returns

200 OK with the object shown in the response.

More details

Returns whether FOCUS export is switched on for the workspace and its exports of the last 7 days, newest first, at most 20. The list has no download links; get them with GetFocusExport.

Needs 'view' access to invoices. An API key can call it.

Response fields

  • enabledboolean

    Whether FOCUS export is switched on for the workspace.

  • from, tostring

    The first and last billing period of the export, as YYYY-MM.

  • rowCount, documentCountnumber

    The rows in the dataset and the invoices, debit notes and credit notes they come from.

  • expiresAtstring

    When Pleaxy deletes the export's files, 7 days after it was created.

Errors

  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/focus-exports
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-exports" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "enabled": boolean,
   "exports": [
      {
         "id": "string",
         "status": "ready",
         "createdAt": "string",
         "version": "1.2" | "1.4",
         "include": "all" | "non_cloud",
         "from": "string",
         "to": "string",
         "format": "csv" | "parquet",
         "rowCount": number,
         "documentCount": number,
         "commitmentCount": number,
         "expiresAt": "string"
      }
   ]
}

Create FOCUS export

Exports the invoices of a range of months as a FOCUS dataset.

POST/v1/workspaces/{regionId}/focus-exports

Body

  • fromstringRequired

    The first billing period, as YYYY-MM.

  • tostringRequired

    The last billing period, as YYYY-MM, included. The range spans at most 36 months.

  • version"1.2" | "1.4"

    The FOCUS version. 1.2 when absent. A 1.4 export can also carry a Contract Commitment dataset.

  • include"all" | "non_cloud"

    non_cloud leaves out cloud and AI providers' invoices, which a FinOps tool can read from the providers' own FOCUS exports. all when absent.

  • format"csv" | "parquet"

    The file format. csv when absent.

Returns

201 Created with the object shown in the response.

More details

Writes the workspace's invoices, debit notes and accepted credit notes for the billing periods from..to as a FOCUS Cost and Usage dataset with a metadata file. There is one row per line, tax entry and adjustment; credit notes are negative; amounts stay in each document's currency. The response has download links valid for 15 minutes, and the files are kept 7 days. An export changes nothing in the workspace.

Needs 'view' access to invoices. An API key can call it.

Response fields

  • from, tostring

    The first and last billing period of the export, as YYYY-MM.

  • rowCount, documentCountnumber

    The rows in the dataset and the invoices, debit notes and credit notes they come from.

  • expiresAtstring

    When Pleaxy deletes the export's files, 7 days after it was created.

  • downloadUrl, metadataUrlstring

    Links to the dataset and its metadata file, valid for 15 minutes. Call GetFocusExport for fresh links.

  • commitmentsUrlstring

    A link to the Contract Commitment dataset, present only when the export has one.

Errors

  • 400 Bad Request - from or to isn't a month written as YYYY-MM, from is after to, or the range spans more than 36 months.
  • 404 Not Found - FOCUS export isn't switched on for this workspace ("FOCUS export isn't switched on for this workspace yet.").
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/focus-exports
Request
POST /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/focus-exports
{
   "from": "2026-07",
   "to": "2026-09",
   "include": "non_cloud"
}
Response · 201 Created
{
   "id": "FE-mhu8x2k04f9a1c",
   "status": "ready",
   "createdAt": "2026-11-11T15:04:05.000Z",
   "version": "1.2",
   "include": "non_cloud",
   "from": "2026-07",
   "to": "2026-09",
   "format": "csv",
   "rowCount": 412,
   "documentCount": 57,
   "expiresAt": "2026-11-18T15:04:05.000Z",
   "downloadUrl": "https://...",
   "metadataUrl": "https://..."
}

Get FOCUS export

Gets one FOCUS export with fresh download links.

GET/v1/workspaces/{regionId}/focus-exports/{exportId}

Parameters

  • exportIdstringRequired

    The export's id, as CreateFocusExport returns it.

Returns

200 OK with the object shown in the response.

More details

Returns one export of the last 7 days with new links to its dataset and metadata file, valid for 15 minutes.

Needs 'view' access to invoices. An API key can call it.

Response fields

  • from, tostring

    The first and last billing period of the export, as YYYY-MM.

  • rowCount, documentCountnumber

    The rows in the dataset and the invoices, debit notes and credit notes they come from.

  • expiresAtstring

    When Pleaxy deletes the export's files, 7 days after it was created.

  • downloadUrl, metadataUrlstring

    Links to the dataset and its metadata file, valid for 15 minutes. Call GetFocusExport for fresh links.

  • commitmentsUrlstring

    A link to the Contract Commitment dataset, present only when the export has one.

Errors

  • 404 Not Found - No export in this workspace has this id, it has expired (exports are kept 7 days), or FOCUS export isn't switched on for this workspace.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/focus-exports/{exportId}
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-exports/{exportId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "id": "string",
   "status": "ready",
   "createdAt": "string",
   "version": "1.2" | "1.4",
   "include": "all" | "non_cloud",
   "from": "string",
   "to": "string",
   "format": "csv" | "parquet",
   "rowCount": number,
   "documentCount": number,
   "commitmentCount": number,
   "expiresAt": "string",
   "downloadUrl": "string",
   "metadataUrl": "string",
   "commitmentsUrl": "string"
}

List FOCUS sources

Lists the workspace's FOCUS sources with their last run, and whether import is on.

GET/v1/workspaces/{regionId}/focus-sources

Returns

200 OK with the object shown in the response.

More details

Returns whether FOCUS import is switched on and the workspace's FOCUS sources, each with its last run, the months it has stored and its most common tag keys.

Needs 'view' access to invoices.

Response fields

  • enabledboolean

    Whether FOCUS import is switched on for the workspace.

  • kindstring

    upload: files you upload. aws_s3: an AWS Data Exports FOCUS export. azure_blob: an Azure Cost Management FOCUS export. gcp_bigquery: Google Cloud's FOCUS table. oci: Oracle Cloud's FOCUS reports. s3_compatible: a bucket on any S3-compatible storage.

  • periodsArray<string>

    The months the source has stored figures for, as YYYY-MM.

  • lastRunobject

    The last read: the months, files and rows read, the rows skipped by reason, and failure.reason when status is failed.

  • tagKeysArray<string>

    The most common tag keys in the source's rows.

  • s3.keyHintstring

    A short hint of which secret access key is stored. The secret itself is never returned.

Errors

  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/focus-sources
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "enabled": boolean,
   "sources": [
      {
         "id": "string",
         "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
         "label": "string",
         "provider": "aws" | "azure" | "gcp" | "oci",
         "connectionId": "string",
         "aws": { "bucket": "string", "prefix": "string", "region": "string" },
         "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
         "gcp": { "table": "string" },
         "oci": { "region": "string" },
         "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
         "periods": [ "string" ],
         "lastRun": {
            "runId": "string",
            "startedAt": "string",
            "finishedAt": "string",
            "status": "ok" | "partial" | "failed",
            "trigger": "schedule" | "manual" | "upload",
            "periods": [ "string" ],
            "files": number,
            "rows": number,
            "skipped": number,
            "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
            "ignoredFiles": number,
            "version": "string",
            "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
         },
         "tagKeys": [ "string" ],
         "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
         "createdAt": "string",
         "updatedAt": "string"
      }
   ]
}

Create FOCUS source

Adds a provider's FOCUS export as a source Pleaxy reads every day.

POST/v1/workspaces/{regionId}/focus-sources

Body

  • kind"aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible"Required

    Where the FOCUS data is. Send the object of the same provider beside it.

  • labelstring

    Optional. A name for the source.

  • connectionIdstring

    The cloud connection the source belongs to, as ListCloudConnections returns it. Required for every kind but s3_compatible.

  • awsobject

    For aws_s3: the bucket AWS Data Exports writes to, the export's prefix (its S3 prefix and export name) and the bucket's region.

  • azureobject

    For azure_blob: the storage account, the container, and the export's directory.

  • gcpobject

    For gcp_bigquery: the FOCUS table or view, as project.dataset.table.

  • ociobject

    For oci: the tenancy's home region.

  • s3object

    For s3_compatible: the storage's HTTPS endpoint, region, bucket and prefix, and an access key that can read it. The secret is stored encrypted and never returned.

Returns

201 Created with the object shown in the response.

More details

Adds a FOCUS source. A cloud's source (aws_s3, azure_blob, gcp_bigquery or oci) belongs to one of the workspace's cloud connections of the same provider; it then becomes the source of that connection's AI lines, in place of the connector's own AI read. An s3_compatible source brings its own access key. Pleaxy reads a source daily, and at once with SyncFocusSource. A connection has at most one FOCUS source.

Signed-in session only, with 'edit' access to invoices: a source opens a read path into your cloud account, so a person adds and removes it.

Response fields

  • kindstring

    upload: files you upload. aws_s3: an AWS Data Exports FOCUS export. azure_blob: an Azure Cost Management FOCUS export. gcp_bigquery: Google Cloud's FOCUS table. oci: Oracle Cloud's FOCUS reports. s3_compatible: a bucket on any S3-compatible storage.

  • periodsArray<string>

    The months the source has stored figures for, as YYYY-MM.

  • lastRunobject

    The last read: the months, files and rows read, the rows skipped by reason, and failure.reason when status is failed.

  • tagKeysArray<string>

    The most common tag keys in the source's rows.

  • s3.keyHintstring

    A short hint of which secret access key is stored. The secret itself is never returned.

Errors

  • 400 Bad Request - A field is missing or invalid, the connection is of another cloud than kind, or the connection already has a FOCUS source.
  • 403 Forbidden - The caller isn't a signed-in person (for example, an API key), or lacks 'edit' access to invoices.
  • 404 Not Found - No cloud connection in this workspace has this connectionId, or FOCUS import isn't switched on for this workspace.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
POST /v1/workspaces/{regionId}/focus-sources
Request
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "kind": "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "secretAccessKey": "string" }
}
Response · 201 Created
{
   "id": "string",
   "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "provider": "aws" | "azure" | "gcp" | "oci",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
   "periods": [ "string" ],
   "lastRun": {
      "runId": "string",
      "startedAt": "string",
      "finishedAt": "string",
      "status": "ok" | "partial" | "failed",
      "trigger": "schedule" | "manual" | "upload",
      "periods": [ "string" ],
      "files": number,
      "rows": number,
      "skipped": number,
      "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
      "ignoredFiles": number,
      "version": "string",
      "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
   },
   "tagKeys": [ "string" ],
   "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
   "createdAt": "string",
   "updatedAt": "string"
}

Get FOCUS source

Gets one FOCUS source with its last run.

GET/v1/workspaces/{regionId}/focus-sources/{sourceId}

Parameters

  • sourceIdstringRequired

    The FOCUS source's id, as ListFocusSources returns it.

Returns

200 OK with the object shown in the response.

More details

Returns one FOCUS source with its last run. Poll it after SyncFocusSource or CompleteFocusUpload to see when the read has finished.

Needs 'view' access to invoices.

Response fields

  • kindstring

    upload: files you upload. aws_s3: an AWS Data Exports FOCUS export. azure_blob: an Azure Cost Management FOCUS export. gcp_bigquery: Google Cloud's FOCUS table. oci: Oracle Cloud's FOCUS reports. s3_compatible: a bucket on any S3-compatible storage.

  • periodsArray<string>

    The months the source has stored figures for, as YYYY-MM.

  • lastRunobject

    The last read: the months, files and rows read, the rows skipped by reason, and failure.reason when status is failed.

  • tagKeysArray<string>

    The most common tag keys in the source's rows.

  • s3.keyHintstring

    A short hint of which secret access key is stored. The secret itself is never returned.

Errors

  • 404 Not Found - No FOCUS source in this workspace has this id, or FOCUS import isn't switched on for this workspace.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/focus-sources/{sourceId}
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "id": "string",
   "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "provider": "aws" | "azure" | "gcp" | "oci",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
   "periods": [ "string" ],
   "lastRun": {
      "runId": "string",
      "startedAt": "string",
      "finishedAt": "string",
      "status": "ok" | "partial" | "failed",
      "trigger": "schedule" | "manual" | "upload",
      "periods": [ "string" ],
      "files": number,
      "rows": number,
      "skipped": number,
      "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
      "ignoredFiles": number,
      "version": "string",
      "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
   },
   "tagKeys": [ "string" ],
   "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
   "createdAt": "string",
   "updatedAt": "string"
}

Sync FOCUS source

Reads a FOCUS source now, in the background.

POST/v1/workspaces/{regionId}/focus-sources/{sourceId}/sync

Parameters

  • sourceIdstringRequired

    The FOCUS source's id, as ListFocusSources returns it.

Returns

202 Accepted with the object shown in the response.

More details

Starts a read of the source in the background, re-reading the months it holds, and returns the source. Its lastRun shows the result once the read has finished.

Needs 'edit' access to invoices. An API key can call it.

Response fields

  • kindstring

    upload: files you upload. aws_s3: an AWS Data Exports FOCUS export. azure_blob: an Azure Cost Management FOCUS export. gcp_bigquery: Google Cloud's FOCUS table. oci: Oracle Cloud's FOCUS reports. s3_compatible: a bucket on any S3-compatible storage.

  • periodsArray<string>

    The months the source has stored figures for, as YYYY-MM.

  • lastRunobject

    The last read: the months, files and rows read, the rows skipped by reason, and failure.reason when status is failed.

  • tagKeysArray<string>

    The most common tag keys in the source's rows.

  • s3.keyHintstring

    A short hint of which secret access key is stored. The secret itself is never returned.

Errors

  • 400 Bad Request - The source is the uploads source, which is read when a file arrives: upload the file again to re-read it.
  • 404 Not Found - No FOCUS source in this workspace has this id, or FOCUS import isn't switched on for this workspace.
  • 503 Service Unavailable - The read can't be started right now. Try again in a few minutes.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/focus-sources/{sourceId}/sync
Request
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}/sync" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 202 Accepted
{
   "id": "string",
   "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "provider": "aws" | "azure" | "gcp" | "oci",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
   "periods": [ "string" ],
   "lastRun": {
      "runId": "string",
      "startedAt": "string",
      "finishedAt": "string",
      "status": "ok" | "partial" | "failed",
      "trigger": "schedule" | "manual" | "upload",
      "periods": [ "string" ],
      "files": number,
      "rows": number,
      "skipped": number,
      "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
      "ignoredFiles": number,
      "version": "string",
      "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
   },
   "tagKeys": [ "string" ],
   "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
   "createdAt": "string",
   "updatedAt": "string"
}

Delete FOCUS source

Removes a FOCUS source with the months it stored.

DELETE/v1/workspaces/{regionId}/focus-sources/{sourceId}

Parameters

  • sourceIdstringRequired

    The FOCUS source's id, as ListFocusSources returns it.

Returns

200 OK with the object shown in the response.

More details

Removes the source with the months and AI lines it stored. The connector's own AI read resumes for its cloud connection.

Signed-in session only, with 'edit' access to invoices: a source opens a read path into your cloud account, so a person adds and removes it.

Errors

  • 403 Forbidden - The caller isn't a signed-in person (for example, an API key), or lacks 'edit' access to invoices.
  • 404 Not Found - No FOCUS source in this workspace has this id, or FOCUS import isn't switched on for this workspace.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
DELETE /v1/workspaces/{regionId}/focus-sources/{sourceId}
Request
curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "removed": true
}

Get FOCUS source period

Gets one stored month of a FOCUS source, by invoice, cost center and issuer.

GET/v1/workspaces/{regionId}/focus-sources/{sourceId}/periods/{period}

Parameters

  • sourceIdstringRequired

    The FOCUS source's id, as ListFocusSources returns it.

  • periodstringRequired

    The month, as YYYY-MM.

Returns

200 OK with the object shown in the response.

More details

Returns one stored month of a source: its totals by currency, each invoice by number with its amounts by category and service, spend by cost center and the totals by issuer.

Needs 'view' access to invoices.

Response fields

  • totalsobject

    The month's billed total, by currency code.

  • invoicesArray<object>

    Each invoice the month's rows name, with its total and its amounts by category and by service.

  • costCentersArray<object>

    The month's spend by cost center, as the workspace's tag attribution rules assign it.

Errors

  • 400 Bad Request - period isn't a month written as YYYY-MM.
  • 404 Not Found - The source has no stored figures for this month, no FOCUS source in this workspace has this id, or FOCUS import isn't switched on for this workspace.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/focus-sources/{sourceId}/periods/{period}
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}/periods/{period}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "sourceId": "string",
   "period": "string",
   "rows": number,
   "version": "string",
   "asOf": "string",
   "totals": { "USD": number },
   "issuers": { "string": { "USD": number } },
   "invoices": [
      {
         "issuer": "string",
         "billingAccountId": "string",
         "invoiceId": "string",
         "currency": "string",
         "total": number,
         "byCategory": { "string": number },
         "byService": { "string": number },
         "corrections": number
      }
   ],
   "costCenters": [ { "costCenter": "string", "serviceCategory": "string", "currency": "string", "amount": number } ]
}

Create FOCUS upload

Starts the upload of a FOCUS file and returns the URL to send it to.

POST/v1/workspaces/{regionId}/focus-sources/uploads

Body

  • fileNamestringRequired

    The file's name, ending in .csv or .csv.gz.

Returns

201 Created with the object shown in the response.

More details

Starts a FOCUS file upload. The file is CSV or gzipped CSV (.csv or .csv.gz), up to 500 MB. PUT it to uploadUrl with the returned contentType, then call CompleteFocusUpload. The URL is valid for a few minutes. Uploaded files go to the workspace's uploads source, sourceId.

Needs 'edit' access to invoices. An API key can call it.

Errors

  • 400 Bad Request - The file name doesn't end in .csv or .csv.gz ("Upload a FOCUS file as CSV, or gzipped CSV (.csv.gz). Parquet files are read in a later release.").
  • 404 Not Found - FOCUS import isn't switched on for this workspace ("FOCUS import isn't switched on for this workspace yet.").
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/focus-sources/uploads
Request
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/uploads" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "fileName": "string"
}
Response · 201 Created
{
   "sourceId": "string",
   "uploadId": "string",
   "uploadUrl": "string",
   "contentType": "string",
   "maxBytes": number
}

Complete FOCUS upload

Tells Pleaxy an uploaded FOCUS file is in place, so it is read.

POST/v1/workspaces/{regionId}/focus-sources/uploads/{uploadId}/complete

Parameters

  • uploadIdstringRequired

    The upload's id, as CreateFocusUpload returns it.

Returns

202 Accepted with the object shown in the response.

More details

Says the file is uploaded. Pleaxy reads it in the background and returns the uploads source; its lastRun shows the result once the read has finished.

Needs 'edit' access to invoices. An API key can call it.

Response fields

  • kindstring

    upload: files you upload. aws_s3: an AWS Data Exports FOCUS export. azure_blob: an Azure Cost Management FOCUS export. gcp_bigquery: Google Cloud's FOCUS table. oci: Oracle Cloud's FOCUS reports. s3_compatible: a bucket on any S3-compatible storage.

  • periodsArray<string>

    The months the source has stored figures for, as YYYY-MM.

  • lastRunobject

    The last read: the months, files and rows read, the rows skipped by reason, and failure.reason when status is failed.

  • tagKeysArray<string>

    The most common tag keys in the source's rows.

  • s3.keyHintstring

    A short hint of which secret access key is stored. The secret itself is never returned.

Errors

  • 400 Bad Request - The file is over 500 MB, or uploadId isn't an upload id.
  • 404 Not Found - No upload with this id is waiting in this workspace: upload the file again. Also when FOCUS import isn't switched on for this workspace.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/focus-sources/uploads/{uploadId}/complete
Request
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/uploads/{uploadId}/complete" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 202 Accepted
{
   "id": "string",
   "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "provider": "aws" | "azure" | "gcp" | "oci",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
   "periods": [ "string" ],
   "lastRun": {
      "runId": "string",
      "startedAt": "string",
      "finishedAt": "string",
      "status": "ok" | "partial" | "failed",
      "trigger": "schedule" | "manual" | "upload",
      "periods": [ "string" ],
      "files": number,
      "rows": number,
      "skipped": number,
      "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
      "ignoredFiles": number,
      "version": "string",
      "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
   },
   "tagKeys": [ "string" ],
   "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
   "createdAt": "string",
   "updatedAt": "string"
}

List FOCUS issuers

Lists the invoice issuers in the stored FOCUS months and the supplier each maps to.

GET/v1/workspaces/{regionId}/focus-sources/issuers

Returns

200 OK with the object shown in the response.

More details

Returns every invoice issuer in the stored FOCUS months (the last three per source), with what it billed by currency and the supplier it maps to, if any.

Needs 'view' access to invoices.

Response fields

  • issuerstring

    The invoice issuer's name as the FOCUS files give it.

  • mappedBy"person" | "name"

    person: someone mapped the issuer to the supplier. name: Pleaxy matched a well-known issuer (AWS, Microsoft, Google, Oracle) by its name. Absent when the issuer has no supplier.

  • totalsobject

    What the issuer billed in the stored months, by currency code.

Errors

  • 404 Not Found - FOCUS import isn't switched on for this workspace ("FOCUS import isn't switched on for this workspace yet.").
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/focus-sources/issuers
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/issuers" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
[
   {
      "issuer": "string",
      "supplierConnectionId": "string",
      "supplierName": "string",
      "mappedBy": "person" | "name",
      "totals": { "USD": number }
   }
]

Map FOCUS issuer

Maps a FOCUS invoice issuer to one of your suppliers, or forgets the mapping.

PUT/v1/workspaces/{regionId}/focus-sources/issuers/{issuer}

Parameters

  • issuerstringRequired

    The issuer's name as the FOCUS files give it, URL-encoded.

Body

  • supplierConnectionIdstring | null

    The supplier's connection id. null, or leaving it out, forgets the mapping.

Returns

200 OK with the object shown in the response.

More details

Maps an invoice issuer to one of the workspace's suppliers. Returns the issuers as ListFocusIssuers does.

Needs 'edit' access to invoices. An API key can call it.

Response fields

  • issuerstring

    The invoice issuer's name as the FOCUS files give it.

  • mappedBy"person" | "name"

    person: someone mapped the issuer to the supplier. name: Pleaxy matched a well-known issuer (AWS, Microsoft, Google, Oracle) by its name. Absent when the issuer has no supplier.

  • totalsobject

    What the issuer billed in the stored months, by currency code.

Errors

  • 400 Bad Request - The issuer's name is empty or too long.
  • 404 Not Found - No supplier in this workspace has this supplierConnectionId, or FOCUS import isn't switched on for this workspace.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
PUT /v1/workspaces/{regionId}/focus-sources/issuers/{issuer}
Request
curl -X PUT "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/issuers/{issuer}" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "supplierConnectionId": "string" | null
}
Response · 200 OK
[
   {
      "issuer": "string",
      "supplierConnectionId": "string",
      "supplierName": "string",
      "mappedBy": "person" | "name",
      "totals": { "USD": number }
   }
]
Talk to us