# `bls__bls_get_latest`

**Get Latest BLS Observation**

Return the single most recent observation for one or more BLS series. Use for "what is X right now" questions — the current unemployment rate, the latest CPI reading, etc. Each series consumes one API query against the 500/day limit; for the current value of many series, bls_get_series with a 1-year window is more quota-efficient (one query for up to 50 series). Recommended limit: 10 series; maximum: 50.

- Server: [US Bureau of Labor Statistics](https://gateway.mcpharbor.dev/docs/servers/bls) (`dev.mcpharbor.gateway/bls`)
- Price per call: $0.0001 (100 micro-USD); only tools/call is charged
- Endpoint: `https://gateway.mcpharbor.dev/mcp` or `https://gateway.mcpharbor.dev/mcp/bls`
- Upstream tool: exposed by the provider; called through this gateway as `bls__bls_get_latest`
- Provider terms: <https://www.bls.gov/developers/termsOfService.htm> (verified 2026-09-19)
- Upstream API documentation: <https://www.bls.gov/developers/>
- Rate limit: 450 requests per 24 hours
- Attribution required: "BLS.gov cannot vouch for the data or analyses derived from these data after the data have been retrieved from BLS.gov", plus cite BLS as source

## Parameters

- `series_ids` (array, required): One or more BLS SeriesIDs (1–50). Each consumes one daily API query. Use bls_search_series to resolve concepts to SeriesIDs. Recommended: ≤10 series.

## Example call

Request headers and body:

```http
POST /mcp HTTP/1.1
Host: gateway.mcpharbor.dev
Authorization: Bearer <your gateway API key>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: bls__bls_get_latest
```

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "example-agent",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/protocolVersion": "2026-07-28"
    },
    "arguments": {
      "series_ids": []
    },
    "name": "bls__bls_get_latest"
  }
}
```

A successful response:

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "_meta": {
      "dev.mcpharbor.gateway/call": {
        "chargedMicroUsd": 100,
        "id": "<the id of this charge>"
      }
    },
    "content": [
      {
        "text": "<whatever the upstream tool returned>",
        "type": "text"
      }
    ],
    "resultType": "complete"
  }
}
```

This call costs $0.0001 (100 micro-USD). Reading this page and listing the tool cost nothing.
The `dev.mcpharbor.gateway/call` record in the result is the receipt for that charge. Each
POST is metered separately, so sending the same call again buys another one: see
[agent.txt](https://gateway.mcpharbor.dev/agent.txt), section 7, before retrying.

## Attribution

This provider requires the attribution below wherever you use results from its tools.
Reproduce it verbatim:

> "BLS.gov cannot vouch for the data or analyses derived from these data after the data have been retrieved from BLS.gov", plus cite BLS as source

## Tool definition

Exactly as `tools/list` returns it (free):

```json
{
  "_meta": {
    "dev.mcpharbor.gateway/pricing": {
      "currency": "USD",
      "pricePerCallMicroUsd": 100
    }
  },
  "annotations": {
    "idempotentHint": true,
    "openWorldHint": true,
    "readOnlyHint": true
  },
  "description": "Return the single most recent observation for one or more BLS series. Use for \"what is X right now\" questions — the current unemployment rate, the latest CPI reading, etc. Each series consumes one API query against the 500/day limit; for the current value of many series, bls_get_series with a 1-year window is more quota-efficient (one query for up to 50 series). Recommended limit: 10 series; maximum: 50.",
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "series_ids": {
        "description": "One or more BLS SeriesIDs (1–50). Each consumes one daily API query. Use bls_search_series to resolve concepts to SeriesIDs. Recommended: ≤10 series.",
        "items": {
          "minLength": 1,
          "type": "string"
        },
        "maxItems": 50,
        "minItems": 1,
        "type": "array"
      }
    },
    "required": [
      "series_ids"
    ],
    "type": "object"
  },
  "name": "bls__bls_get_latest",
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "anyOf": [
      {
        "not": {
          "required": [
            "error"
          ]
        },
        "required": [
          "results",
          "succeeded",
          "failed"
        ]
      },
      {
        "required": [
          "error"
        ]
      }
    ],
    "properties": {
      "error": {
        "additionalProperties": {},
        "description": "Present when the call failed. Absent on success.",
        "properties": {
          "code": {
            "description": "JSON-RPC error code for this failure.",
            "maximum": 9007199254740991,
            "minimum": -9007199254740991,
            "type": "integer"
          },
          "data": {
            "additionalProperties": {},
            "properties": {
              "reason": {
                "description": "Machine-readable failure mode. Declared by this tool: `invalid_api_key`: BLS rejected the configured BLS_API_KEY as invalid. `quota_exceeded`: The BLS API 500 query/day limit has been reached. `series_locked`: The BLS database is temporarily locked for the requested series. Other values are possible when a failure originates below the handler.",
                "examples": [
                  "invalid_api_key",
                  "quota_exceeded",
                  "series_locked"
                ],
                "type": "string"
              },
              "recovery": {
                "additionalProperties": {},
                "description": "Actionable next step for the caller.",
                "properties": {
                  "hint": {
                    "type": "string"
                  }
                },
                "required": [
                  "hint"
                ],
                "type": "object"
              },
              "retryable": {
                "description": "Whether retrying may succeed.",
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "message": {
            "description": "Human-readable description of what went wrong.",
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "type": "object"
      },
      "failed": {
        "description": "Series that failed to fetch. Inspect seriesId and error for per-item details. Not-found series appear here rather than as a tool-level error.",
        "items": {
          "additionalProperties": false,
          "description": "A series that could not be fetched, e.g. due to an invalid SeriesID or empty data window.",
          "properties": {
            "error": {
              "description": "Error message. Common values: \"Series does not exist\" (invalid SeriesID — use bls_search_series to find valid IDs), \"No observations returned\" (series exists but has no current data).",
              "type": "string"
            },
            "seriesId": {
              "description": "SeriesID that failed.",
              "type": "string"
            }
          },
          "required": [
            "seriesId",
            "error"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "notice": {
        "description": "Guidance when one or more series failed — e.g. to use bls_search_series to verify SeriesIDs. Absent when all series returned data.",
        "type": "string"
      },
      "results": {
        "description": "Successfully fetched series with their latest observations. Series that failed appear in failed[] instead.",
        "items": {
          "additionalProperties": false,
          "description": "Latest observation result for one BLS series.",
          "properties": {
            "area": {
              "description": "Geographic area when returned by the API.",
              "type": "string"
            },
            "item": {
              "description": "Item/subject when returned by the API.",
              "type": "string"
            },
            "latestObservation": {
              "additionalProperties": false,
              "description": "Most recent observation.",
              "properties": {
                "available": {
                  "description": "False when BLS published the \"-\" missing-value sentinel for this period.",
                  "type": "boolean"
                },
                "footnotes": {
                  "description": "Footnote codes and text, when present.",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "period": {
                  "description": "Observation period code (e.g. \"M12\" for December, \"Q01\" for Q1).",
                  "type": "string"
                },
                "periodName": {
                  "description": "Human-readable period name (e.g. \"December\").",
                  "type": "string"
                },
                "value": {
                  "description": "Raw observation value from BLS. The literal \"-\" means unavailable; check available before arithmetic and read footnotes for the reason.",
                  "type": "string"
                },
                "year": {
                  "description": "Observation year (e.g. \"2024\").",
                  "type": "string"
                }
              },
              "required": [
                "year",
                "period",
                "value",
                "available"
              ],
              "type": "object"
            },
            "seasonal": {
              "description": "Seasonality indicator when returned by the API.",
              "type": "string"
            },
            "seriesId": {
              "description": "BLS SeriesID.",
              "type": "string"
            },
            "title": {
              "description": "Series name when returned by the API.",
              "type": "string"
            }
          },
          "required": [
            "seriesId"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "succeeded": {
        "description": "Number of series with a successfully fetched observation.",
        "type": "number"
      }
    },
    "type": "object"
  },
  "title": "Get Latest BLS Observation"
}
```